@salesforce/templates 66.3.2 → 66.4.0

package/lib/templates/project/reactb2x/_r_/skills/webapp-react-data-visualization/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: webapp-react-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** — use the **`analytics-charts`** skill in `feature-react-chart` (AnalyticsChart component for categorical data).
+- **Line / area chart** — use the **`analytics-charts`** skill in `feature-react-chart` (AnalyticsChart component for 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/lib/templates/project/reactb2x/_r_/skills/webapp-react-data-visualization/implementation/dashboard-layout.md

@@ -0,0 +1,189 @@
+# 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/lib/templates/project/reactb2x/_r_/skills/webapp-react-data-visualization/implementation/donut-chart.md

@@ -0,0 +1,181 @@
+# 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 charts**, use the `AnalyticsChart` component from `feature-react-chart` instead of raw Recharts. See the **`analytics-charts`** skill for usage.
+
+---
+
+## 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/lib/templates/project/reactb2x/_r_/skills/webapp-react-data-visualization/implementation/stat-card.md

@@ -0,0 +1,150 @@
+# 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/lib/templates/project/reactb2x/_r_/skills/webapp-react-interactive-map/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: webapp-react-interactive-map
+description: Adds interactive Leaflet maps with geocoded markers to React pages. Use when the user asks to add a map, show locations on a map, display property pins, add a map view, or integrate mapping into the web application.
+---
+
+# Interactive Map
+
+## When to Use
+
+Use this skill when:
+- Adding an interactive map to a page (property search, store locator, location detail)
+- Displaying one or more markers/pins on a map
+- Converting addresses to map coordinates (geocoding)
+- Building a split-panel layout with map + list
+
+---
+
+## Step 1 — Determine the map use case
+
+Identify the scenario:
+
+- **Multi-marker search** — map shows multiple pins alongside a scrollable list (e.g. property search, store locator)
+- **Single-location detail** — map shows one pin for a specific address (e.g. property detail, contact page)
+- **Static overview** — map centered on a region with no interactive markers
+
+If unclear, ask:
+
+> "Should the map show a single location, multiple markers from a list, or just a general area overview?"
+
+---
+
+## Step 2 — Install dependencies
+
+The map requires `leaflet` and `react-leaflet`. Read `implementation/leaflet-map.md` for the exact dependency setup.
+
+---
+
+## Step 3 — Choose implementation path
+
+Read the corresponding guide:
+
+- **Map component** — read `implementation/leaflet-map.md` for building the reusable `<MapComponent>`.
+- **Geocoding** — read `implementation/geocoding.md` for converting addresses to lat/lng coordinates.
+
+For a multi-marker search page, you will need both.
+
+---
+
+## Step 4 — Wire the map into the page
+
+Depending on the use case:
+
+### Multi-marker search layout
+
+```
+┌──────────────────────────────────────┐
+│  Search bar / filters                │
+├────────────────────┬─────────────────┤
+│                    │  Scrollable     │
+│   Map (2/3)        │  list (1/3)     │
+│                    │                 │
+└────────────────────┴─────────────────┘
+```
+
+- Map takes `~2/3` width on desktop, full width on mobile stacked above the list.
+- List is scrollable with `overflow-y-auto`.
+- Markers are geocoded from addresses in the list.
+
+### Single-location detail
+
+- Place the map below the hero image or address section.
+- Geocode the address on mount, render one marker.
+- Show the map only after coordinates resolve (conditional render).
+
+---
+
+## Verification
+
+Before completing:
+
+1. Map renders with visible tiles (no gray boxes).
+2. Markers appear at correct locations.
+3. Map is responsive (works on mobile widths).
+4. SSR-safe — no `window is not defined` errors during build.
+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.