@salesforce/afv-skills 1.5.0 → 1.5.2

package/skills/building-webapp-data-visualization/implementation/dashboard-layout.md

@@ -1,189 +0,0 @@
-# Dashboard Layout — Implementation Guide
-
-## Anatomy of a dashboard page
-
-A typical dashboard combines stat cards, charts, and data tables:
-
-```
-┌────────────────────────────────────────────────────┐
-│  Search / global action bar                         │
-├──────────┬──────────┬──────────────────────────────┤
-│ Stat 1   │ Stat 2   │ Stat 3                       │
-├──────────┴──────────┴──────┬───────────────────────┤
-│                            │                       │
-│  Data table / list         │  Donut chart          │
-│  (70% width)               │  (30% width)          │
-│                            │                       │
-└────────────────────────────┴───────────────────────┘
-```
-
----
-
-## Layout implementation
-
-```tsx
-import { PageContainer } from "@/components/layout/PageContainer";
-import { StatCard } from "@/components/StatCard";
-import { DonutChart } from "@/components/DonutChart";
-
-export default function Dashboard() {
-  return (
-    <PageContainer>
-      <div className="max-w-7xl mx-auto space-y-6">
-        {/* Search bar */}
-        <div>{/* global search component */}</div>
-
-        {/* Main content: 70/30 split */}
-        <div className="grid grid-cols-1 lg:grid-cols-[70%_30%] gap-6">
-          <div className="space-y-6">
-            {/* Stat cards row */}
-            <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
-              <StatCard title="Metric A" value={42} />
-              <StatCard title="Metric B" value={18} />
-              <StatCard title="Metric C" value={7} />
-            </div>
-
-            {/* Data table */}
-            <div>{/* table component */}</div>
-          </div>
-
-          {/* Sidebar chart */}
-          <div>
-            <DonutChart title="Distribution" data={chartData} />
-          </div>
-        </div>
-      </div>
-    </PageContainer>
-  );
-}
-```
-
----
-
-## Responsive behavior
-
-| Breakpoint | Layout |
-|------------|--------|
-| Mobile (`< 768px`) | Single column, everything stacked |
-| Tablet (`md`) | Stat cards in 3-col grid, rest stacked |
-| Desktop (`lg`) | 70/30 split for table + chart |
-
-Key Tailwind classes:
-
-```
-grid grid-cols-1 lg:grid-cols-[70%_30%] gap-6
-grid grid-cols-1 md:grid-cols-3 gap-6
-```
-
----
-
-## Loading state
-
-Show a full-page loading state while dashboard data is being fetched:
-
-```tsx
-if (loading) {
-  return (
-    <PageContainer>
-      <div className="flex items-center justify-center min-h-[400px]">
-        <p className="text-muted-foreground">Loading dashboard…</p>
-      </div>
-    </PageContainer>
-  );
-}
-```
-
-Or use a skeleton layout:
-
-```tsx
-if (loading) {
-  return (
-    <PageContainer>
-      <div className="max-w-7xl mx-auto space-y-6">
-        <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
-          {[1, 2, 3].map((i) => (
-            <div key={i} className="h-28 animate-pulse rounded-xl bg-muted" />
-          ))}
-        </div>
-        <div className="grid grid-cols-1 lg:grid-cols-[70%_30%] gap-6">
-          <div className="h-64 animate-pulse rounded-xl bg-muted" />
-          <div className="h-64 animate-pulse rounded-xl bg-muted" />
-        </div>
-      </div>
-    </PageContainer>
-  );
-}
-```
-
----
-
-## Data fetching pattern
-
-Use `useEffect` with cancellation for dashboard metrics:
-
-```ts
-const [metrics, setMetrics] = useState<Metrics | null>(null);
-const [loading, setLoading] = useState(true);
-
-useEffect(() => {
-  let cancelled = false;
-  (async () => {
-    try {
-      setLoading(true);
-      const data = await fetchDashboardMetrics();
-      if (!cancelled) setMetrics(data);
-    } catch (error) {
-      if (!cancelled) console.error("Error loading metrics:", error);
-    } finally {
-      if (!cancelled) setLoading(false);
-    }
-  })();
-  return () => { cancelled = true; };
-}, []);
-```
-
----
-
-## Combining multiple data sources
-
-Dashboards often aggregate data from several APIs. Load them in parallel:
-
-```ts
-const [metrics, setMetrics] = useState<Metrics | null>(null);
-const [requests, setRequests] = useState<Request[]>([]);
-const [loading, setLoading] = useState(true);
-
-useEffect(() => {
-  let cancelled = false;
-  Promise.all([fetchMetrics(), fetchRecentRequests()])
-    .then(([metricsData, requestsData]) => {
-      if (!cancelled) {
-        setMetrics(metricsData);
-        setRequests(requestsData);
-      }
-    })
-    .catch((err) => {
-      if (!cancelled) console.error(err);
-    })
-    .finally(() => {
-      if (!cancelled) setLoading(false);
-    });
-  return () => { cancelled = true; };
-}, []);
-```
-
----
-
-## PageContainer wrapper
-
-A simple wrapper for consistent page padding:
-
-```tsx
-interface PageContainerProps {
-  children: React.ReactNode;
-}
-
-export function PageContainer({ children }: PageContainerProps) {
-  return <div className="p-6">{children}</div>;
-}
-```

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

@@ -1,181 +0,0 @@
-# Donut / Pie Chart — Implementation Guide
-
-Requires **recharts** (install from the web app directory; see SKILL.md Step 2).
-
----
-
-## Data structure
-
-Charts expect an array of objects with `name`, `value`, and `color`:
-
-```ts
-interface ChartData {
-  name: string;
-  value: number;
-  color: string;
-}
-```
-
----
-
-## Donut chart component
-
-Create at `components/DonutChart.tsx`:
-
-```tsx
-import React from "react";
-import { PieChart, Pie, Cell, ResponsiveContainer } from "recharts";
-import { Card } from "@/components/ui/card";
-
-interface ChartData {
-  name: string;
-  value: number;
-  color: string;
-}
-
-interface DonutChartProps {
-  title: string;
-  data: ChartData[];
-}
-
-export const DonutChart: React.FC<DonutChartProps> = ({ title, data }) => {
-  const total = data.reduce((sum, item) => sum + item.value, 0);
-  const mainPercentage = total > 0 ? Math.round((data[0]?.value / total) * 100) : 0;
-
-  return (
-    <Card className="p-4 border-gray-200 shadow-sm flex flex-col">
-      <h3 className="text-sm font-medium text-primary mb-2 uppercase tracking-wide">
-        {title}
-      </h3>
-
-      <div className="relative flex items-center justify-center">
-        <ResponsiveContainer width="100%" height={300}>
-          <PieChart>
-            <Pie
-              data={data}
-              cx="50%"
-              cy="50%"
-              innerRadius={70}
-              outerRadius={110}
-              paddingAngle={2}
-              dataKey="value"
-            >
-              {data.map((entry, index) => (
-                <Cell key={`cell-${index}`} fill={entry.color} />
-              ))}
-            </Pie>
-          </PieChart>
-        </ResponsiveContainer>
-
-        {/* Center label */}
-        <div className="absolute inset-0 flex items-center justify-center">
-          <div className="text-center">
-            <div className="text-5xl font-bold text-primary">{mainPercentage}%</div>
-          </div>
-        </div>
-      </div>
-
-      {/* Legend */}
-      <div className="mt-6 grid grid-cols-2 gap-3">
-        {data.map((item, index) => (
-          <div key={index} className="flex items-center gap-2">
-            <div className="w-3 h-3 rounded-full" style={{ backgroundColor: item.color }} />
-            <span className="text-sm text-gray-700">{item.name}</span>
-          </div>
-        ))}
-      </div>
-    </Card>
-  );
-};
-```
-
----
-
-## Key Recharts concepts
-
-| Component | Purpose |
-|-----------|---------|
-| `ResponsiveContainer` | Wraps chart to make it fill its parent's width |
-| `PieChart` | Chart container for pie/donut |
-| `Pie` | The data ring; `innerRadius` > 0 makes it a donut |
-| `Cell` | Individual segment; accepts `fill` color |
-| `paddingAngle` | Gap between segments (degrees) |
-
-### Donut vs Pie
-
-| Property | Donut | Pie |
-|----------|-------|-----|
-| `innerRadius` | `> 0` (e.g. `70`) | `0` |
-| Center label | Yes, positioned absolutely | Not typical |
-
----
-
-## Preparing chart data from raw records
-
-Transform API data into the `ChartData[]` format before passing to the chart:
-
-```tsx
-const CATEGORIES = ["Plumbing", "HVAC", "Electrical"] as const;
-const OTHER_LABEL = "Other";
-const COLORS = ["#7C3AED", "#EC4899", "#14B8A6", "#06B6D4"];
-
-const chartData = useMemo(() => {
-  const counts: Record<string, number> = {};
-  CATEGORIES.forEach((c) => (counts[c] = 0));
-  counts[OTHER_LABEL] = 0;
-
-  records.forEach((record) => {
-    const type = record.category;
-    if (CATEGORIES.includes(type as (typeof CATEGORIES)[number])) {
-      counts[type]++;
-    } else {
-      counts[OTHER_LABEL]++;
-    }
-  });
-
-  return [
-    ...CATEGORIES.map((name, i) => ({ name, value: counts[name], color: COLORS[i] })),
-    { name: OTHER_LABEL, value: counts[OTHER_LABEL], color: COLORS[CATEGORIES.length] },
-  ];
-}, [records]);
-```
-
----
-
-## Color palette recommendations
-
-| Use case | Colors |
-|----------|--------|
-| Categorical (4 items) | `#7C3AED` `#EC4899` `#14B8A6` `#06B6D4` |
-| Status (3 items) | `#22C55E` `#F59E0B` `#EF4444` (green/amber/red) |
-| Sequential | Use opacity variants of one hue: `#7C3AED` at 100%, 75%, 50%, 25% |
-
-Keep chart colors consistent with the app's design system. Define them as constants, not inline values.
-
----
-
-## Other chart types
-
-For **bar charts** and **line / area charts**, see `bar-line-chart.md` in this directory.
-
----
-
-## 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 segments.
-- Consider `prefers-reduced-motion` for chart animations.
-
----
-
-## Common mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Missing `ResponsiveContainer` | Chart won't resize; always wrap in `ResponsiveContainer` |
-| Fixed width/height on `PieChart` | Let `ResponsiveContainer` control sizing |
-| No legend | Add a grid legend below the chart |
-| Inline colors | Extract to constants for consistency |
-| No fallback for empty data | Show "No data" message when `data` is empty |

package/skills/building-webapp-data-visualization/implementation/stat-card.md

@@ -1,150 +0,0 @@
-# Stat Card — Implementation Guide
-
-## What is a stat card
-
-A stat card displays a single KPI metric with an optional trend indicator. Used on dashboards to show at-a-glance numbers like "Total Properties: 42 (+10%)".
-
----
-
-## Component interface
-
-```ts
-interface StatCardProps {
-  title: string;
-  value: number | string;
-  trend?: {
-    value: number;
-    isPositive: boolean;
-  };
-  subtitle?: string;
-  onClick?: () => void;
-}
-```
-
----
-
-## StatCard component
-
-Create at `components/StatCard.tsx`:
-
-```tsx
-import React from "react";
-import { Card } from "@/components/ui/card";
-import { TrendingUp, TrendingDown } from "lucide-react";
-
-interface StatCardProps {
-  title: string;
-  value: number | string;
-  trend?: {
-    value: number;
-    isPositive: boolean;
-  };
-  subtitle?: string;
-  onClick?: () => void;
-}
-
-export const StatCard: React.FC<StatCardProps> = ({ title, value, trend, subtitle, onClick }) => {
-  return (
-    <Card
-      className={`p-4 border-gray-200 shadow-sm relative ${
-        onClick ? "cursor-pointer hover:shadow-lg transition-shadow" : ""
-      }`}
-      onClick={onClick}
-    >
-      <div className="space-y-1">
-        <p className="text-sm font-medium text-muted-foreground uppercase tracking-wide">{title}</p>
-        <div className="flex items-baseline gap-3">
-          <p className="text-4xl font-bold text-primary">{value}</p>
-          {trend && (
-            <span
-              className={`inline-flex items-center gap-1 px-2.5 py-0.5 rounded-full text-sm font-medium ${
-                trend.isPositive
-                  ? "bg-emerald-100 text-emerald-800"
-                  : "bg-pink-100 text-pink-800"
-              }`}
-            >
-              {trend.isPositive ? (
-                <TrendingUp className="w-4 h-4" />
-              ) : (
-                <TrendingDown className="w-4 h-4" />
-              )}
-              {Math.abs(trend.value)}%
-            </span>
-          )}
-        </div>
-        {subtitle && <p className="text-sm text-muted-foreground mt-1">{subtitle}</p>}
-      </div>
-    </Card>
-  );
-};
-```
-
-This version uses Lucide icons (`TrendingUp`/`TrendingDown`) instead of custom SVGs for portability across projects.
-
----
-
-## Layout: stat card grid
-
-Display stat cards in a responsive grid:
-
-```tsx
-<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
-  <StatCard
-    title="Total Properties"
-    value={metrics.totalProperties}
-    trend={{ value: 10, isPositive: true }}
-    subtitle="Last month total 38"
-  />
-  <StatCard
-    title="Units Available"
-    value={metrics.unitsAvailable}
-    trend={{ value: 5, isPositive: false }}
-    subtitle="Last month total 12/42"
-  />
-  <StatCard
-    title="Occupied Units"
-    value={metrics.occupiedUnits}
-    trend={{ value: 8, isPositive: true }}
-    subtitle="Last month total 27"
-  />
-</div>
-```
-
----
-
-## Computing trend values
-
-Calculate trends from current vs previous period:
-
-```ts
-const trends = useMemo(() => {
-  const previousTotal = metrics.totalProperties - Math.round(metrics.totalProperties * 0.1);
-  const trendPercent = previousTotal > 0
-    ? Math.round(((metrics.totalProperties - previousTotal) / previousTotal) * 100)
-    : 0;
-
-  return {
-    value: Math.abs(trendPercent),
-    isPositive: trendPercent >= 0,
-  };
-}, [metrics]);
-```
-
----
-
-## Trend badge color conventions
-
-| Trend | Background | Text | Meaning |
-|-------|------------|------|---------|
-| Positive (up) | `bg-emerald-100` | `text-emerald-800` | Growth, improvement |
-| Negative (down) | `bg-pink-100` | `text-pink-800` | Decline, concern |
-| Neutral | `bg-gray-100` | `text-gray-600` | No change |
-
----
-
-## Accessibility
-
-- Card uses `cursor-pointer` and `hover:shadow-lg` only when `onClick` is provided.
-- Trend icons have implicit meaning from color + direction icon.
-- Stat values use large, bold text for visibility.
-- Title uses `uppercase tracking-wide` for visual hierarchy without heading tags (appropriate in a card grid).

package/skills/building-webapp-react-components/SKILL.md

@@ -1,96 +0,0 @@
----
-name: building-webapp-react-components
-description: "Use when editing any React code in the web application — creating or modifying components, pages, layout, headers, footers, or any TSX/JSX files. Follow this skill for add component, add page, header/footer, and general React UI implementation patterns (shadcn UI and Tailwind CSS)."
----
-
-# React Web App (Components, Pages, Layout)
-
-Use this skill whenever you are editing React/TSX code in the web app (creating or modifying components, pages, header/footer, or layout).
-
-## Step 1 — Identify the type of component
-
-Determine which of these three categories the request falls into, then follow the corresponding section below:
-
-- **Page** — user wants a new routed page (e.g. "add a contacts page", "create a dashboard page", "add a settings section")
-- **Header / Footer** — user wants a site-wide header, footer, nav bar, or page footer that appears on every page
-- **Component** — everything else: a widget, card, table, form, dialog, or other UI element placed within an existing page
-
-If it is not immediately clear from the user's message, ask:
-
-> "Are you looking to add a new page, a site-wide header or footer, or a component within an existing page?"
-
-Then follow the matching section.
-
----
-
-## Clarifying Questions
-
-Ask **one question at a time** and wait for the response before asking the next. Stop when you have enough to build accurately — do not guess or assume.
-
-### For a Page
-
-1. **What is the name and purpose of the page?** (e.g., Contacts, Dashboard, Settings)
-2. **What URL path should it use?** (e.g., `/contacts`, `/dashboard`) — or derive from the page name?
-3. **Should the page appear in the navigation menu?**
-4. **Who can access it?** Public, authenticated users only (`PrivateRoute`), or unauthenticated only (e.g., login — `AuthenticationRoute`)?
-5. **What content or sections should the page include?** (list, form, table, detail view, etc.)
-6. **Does it need to fetch any data?** If so, from where?
-
-### For a Header / Footer
-
-1. **Header, footer, or both?**
-2. **What should the header contain?** (logo/app name, nav links, user avatar, CTA button, etc.)
-3. **What should the footer contain?** (copyright text, links, social icons, etc.)
-4. **Should the header be sticky (fixed to top while scrolling)?**
-5. **Is there a logo or brand name to display?** (or placeholder?)
-6. **Any specific color scheme or style direction?** (dark background, branded primary color, minimal, etc.)
-7. **Should navigation links appear in the header?** If so, which pages?
-
-### For a Component
-
-1. **What should the component do?** (display data, accept input, trigger an action, etc.)
-2. **What page or location should it appear on?**
-3. **Is this shared/reusable across pages, or specific to one feature?** (determines file location)
-4. **What data or props does it need?** (static content, props, fetched data)
-5. **Does it need internal state?** (loading, toggle, form state, etc.)
-6. **Are there any specific shadcn components to use?** (Card, Table, Dialog, Form, etc.)
-7. **Should it appear in a specific layout position?** (full-width, sidebar, inline, etc.)
-
----
-
-## Implementation
-
-Once you have identified the type and gathered answers to the clarifying questions, read and follow the corresponding implementation guide:
-
-- **Page** — read `implementation/page.md` and follow the instructions there.
-- **Header / Footer** — read `implementation/header-footer.md` and follow the instructions there.
-- **Component** — read `implementation/component.md` and follow the instructions there.
-
----
-
-## TypeScript Standards
-
-- **Never use `any`** — use proper types, generics, or `unknown` with type guards.
-- **Event handlers:** `(event: React.FormEvent<HTMLFormElement>): void`
-- **State:** `useState<User | null>(null)` — always provide the type parameter.
-- **No unsafe assertions** (`obj as User`). Use type guards:
-  ```typescript
-  function isUser(obj: unknown): obj is User {
-    return typeof obj === 'object' && obj !== null && typeof (obj as User).id === 'string';
-  }
-  ```
-
----
-
-## Verification (MANDATORY)
-
-Before completing, run from the web app directory `force-app/main/default/webapplications/<appName>/`:
-
-```bash
-cd force-app/main/default/webapplications/<appName> && npm run lint && npm run build
-```
-
-- **Lint:** MUST result in 0 errors.
-- **Build:** MUST succeed (includes TypeScript check).
-
-If either fails, fix the errors and re-run. Do not leave the session with failing quality gates.

package/skills/configuring-webapp-csp-trusted-sites/SKILL.md

@@ -1,90 +0,0 @@
----
-name: configuring-webapp-csp-trusted-sites
-description: "Creates Salesforce CSP Trusted Site metadata when adding external domains. Use when the user adds an external API, CDN, image host, font provider, map tile server, or any third-party URL that the web application needs to load resources from — or when a browser console shows a CSP violation error."
----
-
-# CSP Trusted Sites
-
-## When to Use
-
-Use this skill whenever the application references a new external domain that is not already registered as a CSP Trusted Site. This includes:
-
-- Adding images from a new CDN (Unsplash, Pexels, Cloudinary, etc.)
-- Loading fonts from an external provider (Google Fonts, Adobe Fonts)
-- Calling a third-party API (Open-Meteo, Nominatim, Mapbox, etc.)
-- Loading map tiles from a tile server (OpenStreetMap, Mapbox)
-- Embedding iframes from external services (YouTube, Vimeo)
-- Loading external stylesheets or scripts
-
-Salesforce enforces Content Security Policy (CSP) headers on all web applications. Any external domain not registered as a CSP Trusted Site will be blocked by the browser, causing images to not load, API calls to fail, or fonts to be missing.
-
-**Reference:** [Salesforce CspTrustedSite Object Reference](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_csptrustedsite.htm)
-
----
-
-## Step 1 — Identify external domains
-
-Scan the code for any URLs pointing to external domains. Common patterns:
-
-- `fetch("https://api.example.com/...")` — API calls
-- `<img src="https://images.example.com/..." />` — images
-- `<link href="https://fonts.example.com/..." />` — stylesheets
-- `url="https://tiles.example.com/{z}/{x}/{y}.png"` — map tiles
-- `@import url("https://cdn.example.com/...")` — CSS imports
-
-Extract the **origin** (scheme + host) from each URL. For example:
-- `https://api.open-meteo.com/v1/forecast?lat=...` → `https://api.open-meteo.com`
-- `https://images.unsplash.com/photo-123?w=800` → `https://images.unsplash.com`
-
----
-
-## Step 2 — Check existing CSP Trusted Sites
-
-Before creating a new file, check if the domain already has a CSP Trusted Site:
-
-```bash
-ls force-app/main/default/cspTrustedSites/
-```
-
-If the domain is already registered, no action is needed.
-
----
-
-## Step 3 — Determine the CSP directive(s)
-
-Map the resource type to the correct CSP `isApplicableTo*Src` fields. Read `implementation/metadata-format.md` for the full reference.
-
-Quick reference:
-
-| Resource type | CSP directive field(s) to set `true` |
-|--------------|--------------------------------------|
-| Images (img, background-image) | `isApplicableToImgSrc` |
-| API calls (fetch, XMLHttpRequest) | `isApplicableToConnectSrc` |
-| Fonts (.woff, .woff2, .ttf) | `isApplicableToFontSrc` |
-| Stylesheets (CSS) | `isApplicableToStyleSrc` |
-| Video / audio | `isApplicableToMediaSrc` |
-| Iframes | `isApplicableToFrameSrc` |
-
-**Always also set `isApplicableToConnectSrc` to `true`** — most resources also require connect-src for preflight/redirect handling.
-
----
-
-## Step 4 — Create the metadata file
-
-Read `implementation/metadata-format.md` and follow the instructions to create the `.cspTrustedSite-meta.xml` file.
-
----
-
-## Step 5 — Verify
-
-1. Confirm the file is valid XML and matches the expected schema.
-2. Confirm the file is placed in `force-app/main/default/cspTrustedSites/`.
-3. Confirm only the necessary `isApplicableTo*Src` fields are set to `true`.
-4. 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.