@salesforce/afv-skills 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [
@@ -11,13 +11,14 @@
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
-    "@salesforce/webapp-template-app-react-sample-b2e-experimental": "^1.107.0",
-    "@salesforce/webapp-template-app-react-sample-b2x-experimental": "^1.107.0",
+    "@salesforce/webapp-template-app-react-sample-b2e-experimental": "1.109.1",
+    "@salesforce/webapp-template-app-react-sample-b2x-experimental": "1.109.1",
     "tsx": "^4.21.0"
   },
   "scripts": {
     "validate:skills": "tsx scripts/validate-skills.ts",
     "sync-react-b2e-sample": "node scripts/sync-react-b2e-sample.js",
-    "sync-react-b2x-sample": "node scripts/sync-react-b2x-sample.js"
+    "sync-react-b2x-sample": "node scripts/sync-react-b2x-sample.js",
+    "sync-webapp-skills": "node scripts/sync-webapp-skills.js"
   }
 }

package/skills/accessing-webapp-data/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: accessing-webapp-data
+description: Salesforce data access patterns. Use when adding or modifying any code that fetches data from Salesforce (records, Chatter, Connect API, etc.).
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.graphql"
+---
+
+# Salesforce Data Access
+
+Guidance for accessing Salesforce data from web apps. **All Salesforce data fetches MUST use the Data SDK** (`@salesforce/sdk-data`). The SDK provides authentication, CSRF handling, and correct base URL resolution — direct `fetch` or `axios` calls bypass these and are not allowed.
+
+## Mandatory: Use the Data SDK
+
+> **Every Salesforce data fetch must go through the Data SDK.** Obtain it via `createDataSDK()`, then use `sdk.graphql?.()` or `sdk.fetch?.()`. Never call `fetch()` or `axios` directly for Salesforce endpoints.
+
+## Optional Chaining and Graceful Handling
+
+**Always use optional chaining** when calling `sdk.graphql` or `sdk.fetch` — these methods may be undefined in some surfaces (e.g., Salesforce ACC, MCP Apps). Handle the case where they are not available gracefully:
+
+```typescript
+const sdk = await createDataSDK();
+
+// ✅ Use optional chaining
+const response = await sdk.graphql?.(query);
+
+// ✅ Check before using fetch
+if (!sdk.fetch) {
+  throw new Error("Data SDK fetch is not available in this context");
+}
+const res = await sdk.fetch(url);
+```
+
+For GraphQL, if `sdk.graphql` is undefined, the call returns `undefined` — handle that in your logic (e.g., throw a clear error or return a fallback). For `sdk.fetch`, check availability before calling when the operation is required.
+
+## Preference: GraphQL First
+
+**GraphQL is the preferred method** for querying and mutating Salesforce records. Use it when:
+
+- Querying records (Account, Contact, Opportunity, custom objects)
+- Creating, updating, or deleting records (when GraphQL supports the operation)
+- Fetching related data, filters, sorting, pagination
+
+**Use `sdk.fetch` only when GraphQL is not sufficient.** For REST API usage, invoke the `fetching-rest-api` skill, which documents:
+
+- Chatter API (e.g., `/services/data/v65.0/chatter/users/me`)
+- Connect REST API (e.g., `/services/data/v65.0/connect/file/upload/config`)
+- Apex REST (e.g., `/services/apexrest/auth/login`)
+- UI API REST (e.g., `/services/data/v65.0/ui-api/records/{recordId}`)
+- Einstein LLM Gateway
+
+---
+
+## Getting the SDK
+
+```typescript
+import { createDataSDK } from "@salesforce/sdk-data";
+
+const sdk = await createDataSDK();
+```
+
+---
+
+## Example 1: GraphQL (Preferred)
+
+For record queries and mutations, use GraphQL via the Data SDK. Invoke the `using-graphql` skill for the full workflow (schema exploration, query authoring, codegen, lint validate).
+
+```typescript
+import { createDataSDK, gql } from "@salesforce/sdk-data";
+import type { GetAccountsQuery } from "../graphql-operations-types";
+
+const GET_ACCOUNTS = gql`
+  query GetAccounts {
+    uiapi {
+      query {
+        Account(first: 10) {
+          edges {
+            node {
+              Id
+              Name { value }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+export async function getAccounts() {
+  const sdk = await createDataSDK();
+  const response = await sdk.graphql?.<GetAccountsQuery>(GET_ACCOUNTS);
+
+  if (response?.errors?.length) {
+    throw new Error(response.errors.map((e) => e.message).join("; "));
+  }
+
+  return response?.data?.uiapi?.query?.Account?.edges?.map((e) => e?.node) ?? [];
+}
+```
+
+---
+
+## Example 2: Fetch (When GraphQL Is Not Sufficient)
+
+For REST endpoints that have no GraphQL equivalent, use `sdk.fetch`. **Invoke the `fetching-rest-api` skill** for full documentation of Chatter, Connect REST, Apex REST, UI API REST, and Einstein LLM endpoints.
+
+```typescript
+import { createDataSDK } from "@salesforce/sdk-data";
+
+declare const __SF_API_VERSION__: string;
+const API_VERSION = typeof __SF_API_VERSION__ !== "undefined" ? __SF_API_VERSION__ : "65.0";
+
+export async function getCurrentUser() {
+  const sdk = await createDataSDK();
+  const response = await sdk.fetch?.(`/services/data/v${API_VERSION}/chatter/users/me`);
+
+  if (!response?.ok) throw new Error(`HTTP ${response?.status}`);
+  const data = await response.json();
+  return { id: data.id, name: data.name };
+}
+```
+
+---
+
+## Anti-Patterns (Forbidden)
+
+### Direct fetch to Salesforce
+
+```typescript
+// ❌ FORBIDDEN — bypasses Data SDK auth and CSRF
+const res = await fetch("/services/data/v65.0/chatter/users/me");
+```
+
+### Direct axios to Salesforce
+
+```typescript
+// ❌ FORBIDDEN — bypasses Data SDK
+const res = await axios.get("/services/data/v65.0/chatter/users/me");
+```
+
+### Correct approach
+
+```typescript
+// ✅ CORRECT — use Data SDK
+const sdk = await createDataSDK();
+const res = await sdk.fetch?.("/services/data/v65.0/chatter/users/me");
+```
+
+---
+
+## Clarifying Vague Data Requests
+
+When a user asks about data and the request is vague, **clarify before implementing**. Ask which of the following they want:
+
+- **Application code** — Add or modify code in a specific web app so the app performs the data interaction at runtime (e.g., GraphQL query in the React app)
+- **Local SF CLI** — Run Salesforce CLI commands locally (e.g., `sf data query`, `sf data import tree`) to interact with the org from the terminal
+- **Local example data** — Update or add local fixture/example data files (e.g., JSON in `data/`) for development or testing
+- **Other** — Data export, report generation, setup script, etc.
+
+Do not assume. A request like "fetch accounts" could mean: (1) add a GraphQL query to the app, (2) run `sf data query` in the terminal, or (3) update sample data files. Confirm the intent before proceeding.
+
+---
+
+## Decision Flow
+
+1. **Need to query or mutate Salesforce records?** → Use GraphQL via the Data SDK. Invoke the `using-graphql` skill.
+2. **Need Chatter, Connect REST, Apex REST, UI API REST, or Einstein LLM?** → Use `sdk.fetch`. Invoke the `fetching-rest-api` skill.
+3. **Never** use `fetch`, `axios`, or similar directly for Salesforce API calls.
+
+---
+
+## Reference
+
+- GraphQL workflow: invoke the `using-graphql` skill (`.a4drules/skills/using-graphql/`)
+- REST API via fetch: invoke the `fetching-rest-api` skill (`.a4drules/skills/fetching-rest-api/`)
+- Data SDK package: `@salesforce/sdk-data` (`createDataSDK`, `gql`, `NodeOfConnection`)
+- `createRecord` for UI API record creation: `@salesforce/webapp-experimental/api` (uses Data SDK internally)

package/skills/building-webapp-data-visualization/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: building-webapp-data-visualization
+description: Adds data visualization components (charts, stat cards, KPI metrics) to React pages using Recharts. Use when the user asks to add a chart, graph, donut chart, pie chart, bar chart, stat card, KPI metric, dashboard visualization, or analytics component to the web application.
+---
+
+# Data Visualization
+
+## When to Use
+
+Use this skill when:
+- Adding charts (donut, pie, bar, line, area) to a dashboard or analytics page
+- Displaying KPI/metric stat cards with trend indicators
+- Building a dashboard layout with mixed chart types and summary cards
+
+---
+
+## Step 1 — Determine the visualization type
+
+Identify what the user needs:
+
+- **Donut / pie chart** — categorical breakdown (e.g. issue types, status distribution)
+- **Bar chart** — comparison across categories or time periods
+- **Line / area chart** — trends over time
+- **Stat card** — single KPI metric with optional trend indicator
+- **Combined dashboard** — stat cards + one or more charts
+
+If unclear, ask:
+
+> "What data should the chart display, and would a donut chart, bar chart, line chart, or stat cards work best?"
+
+---
+
+## Step 2 — Install dependencies
+
+All chart types in this skill use **recharts**. Install once from the web app directory:
+
+```bash
+npm install recharts
+```
+
+Recharts is built on D3 and provides declarative React components. No additional CSS is needed.
+
+---
+
+## Step 3 — Choose implementation path
+
+Read the corresponding guide:
+
+- **Bar chart** — read `implementation/bar-line-chart.md` (categorical data)
+- **Line / area chart** — read `implementation/bar-line-chart.md` (time-series data)
+- **Donut / pie chart** — read `implementation/donut-chart.md`
+- **Stat card with trend** — read `implementation/stat-card.md`
+- **Dashboard layout** — read `implementation/dashboard-layout.md`
+
+---
+
+## Verification
+
+Before completing:
+
+1. Chart renders with correct data and colors.
+2. Chart is responsive (resizes with container).
+3. Legend labels match the data categories.
+4. Stat card trends display correct positive/negative indicators.
+5. Run from the web app directory:
+
+```bash
+cd force-app/main/default/webapplications/<appName> && npm run lint && npm run build
+```
+
+- **Lint:** MUST result in 0 errors.
+- **Build:** MUST succeed.

package/skills/building-webapp-data-visualization/implementation/bar-line-chart.md

@@ -0,0 +1,316 @@
+# Bar & Line / Area Chart — Implementation Guide
+
+Requires **recharts** (install from the web app directory; see SKILL.md Step 2).
+
+---
+
+## Data shapes
+
+### Time-series (line / area chart)
+
+Use when data represents a trend over time or ordered sequence.
+
+```ts
+interface TimeSeriesDataPoint {
+  x: string;   // date or label on the x-axis
+  y: number;   // numeric value
+}
+```
+
+Map raw fields to this shape: e.g. `date` → `x`, `revenue` → `y`.
+
+### Categorical (bar chart)
+
+Use when data compares discrete categories.
+
+```ts
+interface CategoricalDataPoint {
+  name: string;   // category label
+  value: number;  // numeric value
+}
+```
+
+Map raw fields to this shape: e.g. `product` → `name`, `sales` → `value`.
+
+### How to decide
+
+| Signal | Type |
+|--------|------|
+| "over time", "trend", date-like keys | Time-series → line chart |
+| "by category", "by X", label-like keys | Categorical → bar chart |
+
+---
+
+## Theme colors
+
+Pick a theme based on the data's sentiment:
+
+| Theme | Stroke / Fill | When to use |
+|-------|---------------|-------------|
+| `green` | `#22c55e` | Growth, gain, positive trend |
+| `red` | `#ef4444` | Decline, loss, negative trend |
+| `neutral` | `#6366f1` | Default or mixed data |
+
+Define colors as constants — do not use inline hex values.
+
+```ts
+const THEME_COLORS = {
+  red: "#ef4444",
+  green: "#22c55e",
+  neutral: "#6366f1",
+} as const;
+
+type ChartTheme = keyof typeof THEME_COLORS;
+```
+
+---
+
+## Line chart component
+
+Create at `components/LineChart.tsx` (or colocate with the page):
+
+```tsx
+import React from "react";
+import {
+  LineChart as RechartsLineChart,
+  Line,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+  Legend,
+  ResponsiveContainer,
+} from "recharts";
+
+const THEME_COLORS = {
+  red: "#ef4444",
+  green: "#22c55e",
+  neutral: "#6366f1",
+} as const;
+
+type ChartTheme = keyof typeof THEME_COLORS;
+
+interface TimeSeriesDataPoint {
+  x: string;
+  y: number;
+}
+
+interface TimeSeriesChartProps {
+  data: TimeSeriesDataPoint[];
+  theme?: ChartTheme;
+  title?: string;
+  className?: string;
+}
+
+export function TimeSeriesChart({
+  data,
+  theme = "neutral",
+  title,
+  className = "",
+}: TimeSeriesChartProps) {
+  if (data.length === 0) {
+    return <p className="text-muted-foreground text-center py-8">No data to display</p>;
+  }
+
+  const color = THEME_COLORS[theme];
+
+  return (
+    <div className={className}>
+      {title && (
+        <h3 className="text-sm font-medium text-primary mb-2 uppercase tracking-wide">
+          {title}
+        </h3>
+      )}
+      <ResponsiveContainer width="100%" height={300}>
+        <RechartsLineChart data={data}>
+          <CartesianGrid strokeDasharray="3 3" />
+          <XAxis dataKey="x" />
+          <YAxis />
+          <Tooltip />
+          <Legend />
+          <Line type="monotone" dataKey="y" stroke={color} strokeWidth={2} dot={false} />
+        </RechartsLineChart>
+      </ResponsiveContainer>
+    </div>
+  );
+}
+```
+
+---
+
+## Bar chart component
+
+Create at `components/BarChart.tsx` (or colocate with the page):
+
+```tsx
+import React from "react";
+import {
+  BarChart as RechartsBarChart,
+  Bar,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+  Legend,
+  ResponsiveContainer,
+} from "recharts";
+
+const THEME_COLORS = {
+  red: "#ef4444",
+  green: "#22c55e",
+  neutral: "#6366f1",
+} as const;
+
+type ChartTheme = keyof typeof THEME_COLORS;
+
+interface CategoricalDataPoint {
+  name: string;
+  value: number;
+}
+
+interface CategoricalChartProps {
+  data: CategoricalDataPoint[];
+  theme?: ChartTheme;
+  title?: string;
+  className?: string;
+}
+
+export function CategoricalChart({
+  data,
+  theme = "neutral",
+  title,
+  className = "",
+}: CategoricalChartProps) {
+  if (data.length === 0) {
+    return <p className="text-muted-foreground text-center py-8">No data to display</p>;
+  }
+
+  const color = THEME_COLORS[theme];
+
+  return (
+    <div className={className}>
+      {title && (
+        <h3 className="text-sm font-medium text-primary mb-2 uppercase tracking-wide">
+          {title}
+        </h3>
+      )}
+      <ResponsiveContainer width="100%" height={300}>
+        <RechartsBarChart data={data}>
+          <CartesianGrid strokeDasharray="3 3" />
+          <XAxis dataKey="name" />
+          <YAxis />
+          <Tooltip />
+          <Legend />
+          <Bar dataKey="value" fill={color} radius={[4, 4, 0, 0]} />
+        </RechartsBarChart>
+      </ResponsiveContainer>
+    </div>
+  );
+}
+```
+
+---
+
+## Area chart variant
+
+For a filled area chart (useful for volume-over-time), swap `Line` for `Area`:
+
+```tsx
+import { AreaChart, Area, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from "recharts";
+
+<ResponsiveContainer width="100%" height={300}>
+  <AreaChart data={data}>
+    <CartesianGrid strokeDasharray="3 3" />
+    <XAxis dataKey="x" />
+    <YAxis />
+    <Tooltip />
+    <Area type="monotone" dataKey="y" stroke={color} fill={color} fillOpacity={0.2} />
+  </AreaChart>
+</ResponsiveContainer>
+```
+
+---
+
+## Chart container wrapper
+
+Wrap any chart in a styled card for consistent spacing:
+
+```tsx
+import { Card } from "@/components/ui/card";
+
+interface ChartContainerProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export function ChartContainer({ children, className = "" }: ChartContainerProps) {
+  return (
+    <Card className={`p-4 border-gray-200 shadow-sm ${className}`}>
+      {children}
+    </Card>
+  );
+}
+```
+
+Usage:
+
+```tsx
+<ChartContainer>
+  <TimeSeriesChart data={monthlyData} theme="green" title="Monthly Revenue" />
+</ChartContainer>
+```
+
+---
+
+## Preparing raw data
+
+Map API responses to the expected shape before passing to the chart:
+
+```tsx
+const timeSeriesData = useMemo(
+  () => apiRecords.map((r) => ({ x: r.date, y: r.revenue })),
+  [apiRecords],
+);
+
+const categoricalData = useMemo(
+  () => apiRecords.map((r) => ({ name: r.product, value: r.sales })),
+  [apiRecords],
+);
+```
+
+---
+
+## Key Recharts concepts
+
+| Component | Purpose |
+|-----------|---------|
+| `ResponsiveContainer` | Wraps chart to fill parent width |
+| `CartesianGrid` | Background grid lines |
+| `XAxis` / `YAxis` | Axis labels; `dataKey` maps to the data field |
+| `Tooltip` | Hover info |
+| `Legend` | Series labels |
+| `Line` | Line series; `type="monotone"` for smooth curves |
+| `Bar` | Bar series; `radius` rounds top corners |
+| `Area` | Filled area; `fillOpacity` controls transparency |
+
+---
+
+## Accessibility
+
+- Always include a text legend (not just colors).
+- Chart should be wrapped in a section with a visible heading.
+- For critical data, provide a text summary or table alternative.
+- Use sufficient color contrast between the chart stroke/fill and background.
+- Consider `prefers-reduced-motion` for chart animations.
+
+---
+
+## Common mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Missing `ResponsiveContainer` | Chart won't resize; always wrap |
+| Fixed width/height on chart | Let `ResponsiveContainer` control sizing |
+| No empty-data handling | Show "No data" message when `data.length === 0` |
+| Inline colors | Extract to `THEME_COLORS` constant |
+| Using raw Recharts for every chart type | Use `DonutChart` (see `donut-chart.md`) for pie/donut |