@salesforce/webapp-template-app-react-sample-b2e-experimental 1.82.0 → 1.83.0

package/dist/.a4drules/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/dist/.a4drules/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/dist/.a4drules/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.

package/dist/.a4drules/skills/webapp-react-interactive-map/implementation/geocoding.md

@@ -0,0 +1,245 @@
+# Geocoding — Implementation Guide
+
+## What is geocoding
+
+Geocoding converts a human-readable address (e.g. "123 Main St, San Francisco, CA") into latitude/longitude coordinates for map display.
+
+---
+
+## Recommended service: OpenStreetMap Nominatim
+
+| Property | Value |
+|----------|-------|
+| Endpoint | `https://nominatim.openstreetmap.org/search` |
+| Cost | Free |
+| API key | None |
+| Rate limit | 1 request/second (enforced by Nominatim usage policy) |
+| Terms | Must set a meaningful `User-Agent` header |
+
+---
+
+## Geocode utility with caching and concurrency control
+
+Create at `utils/geocode.ts`:
+
+```ts
+const CACHE = new Map<string, { lat: number; lng: number }>();
+const MAX_CONCURRENT = 6;
+let inFlight = 0;
+const queue: Array<() => void> = [];
+
+function acquire(): Promise<void> {
+  if (inFlight < MAX_CONCURRENT) {
+    inFlight += 1;
+    return Promise.resolve();
+  }
+  return new Promise<void>((resolve) => {
+    queue.push(() => {
+      inFlight += 1;
+      resolve();
+    });
+  });
+}
+
+function release(): void {
+  inFlight -= 1;
+  const next = queue.shift();
+  if (next) next();
+}
+
+export interface GeocodeResult {
+  lat: number;
+  lng: number;
+}
+
+export async function geocodeAddress(address: string): Promise<GeocodeResult | null> {
+  const key = address.trim().replace(/\s+/g, " ").toLowerCase();
+  if (!key) return null;
+  const cached = CACHE.get(key);
+  if (cached) return cached;
+
+  await acquire();
+  try {
+    const url = new URL("https://nominatim.openstreetmap.org/search");
+    url.searchParams.set("q", address.trim());
+    url.searchParams.set("format", "json");
+    url.searchParams.set("limit", "1");
+    const res = await fetch(url.toString(), {
+      headers: { "User-Agent": "MyApp/1.0 (contact@example.com)" },
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as Array<{ lat?: string; lon?: string }>;
+    const first = data?.[0];
+    if (!first?.lat || !first?.lon) return null;
+    const lat = Number(first.lat);
+    const lng = Number(first.lon);
+    if (Number.isNaN(lat) || Number.isNaN(lng)) return null;
+    const result = { lat, lng };
+    CACHE.set(key, result);
+    return result;
+  } catch {
+    return null;
+  } finally {
+    release();
+  }
+}
+```
+
+### Design decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| In-memory cache | Avoids repeated API calls for the same address within a session |
+| Concurrency limiter (6) | Prevents flooding Nominatim when geocoding many addresses in parallel |
+| Semaphore queue | Requests beyond the limit wait in FIFO order |
+| Null return on failure | Callers decide how to handle missing coordinates (skip marker, show fallback) |
+| `User-Agent` header | Required by Nominatim usage policy; set to your app name and contact |
+
+---
+
+## React hook: useGeocode
+
+For single-address geocoding (e.g. detail pages):
+
+```ts
+import { useState, useEffect } from "react";
+import { geocodeAddress, type GeocodeResult } from "@/utils/geocode";
+
+export function useGeocode(address: string | null | undefined): {
+  coords: GeocodeResult | null;
+  loading: boolean;
+} {
+  const [coords, setCoords] = useState<GeocodeResult | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    if (!address?.trim()) {
+      setCoords(null);
+      setLoading(false);
+      return;
+    }
+    let cancelled = false;
+    setLoading(true);
+    geocodeAddress(address)
+      .then((result) => {
+        if (!cancelled) setCoords(result);
+      })
+      .catch(() => {
+        if (!cancelled) setCoords(null);
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [address?.trim() ?? ""]);
+
+  return { coords, loading };
+}
+```
+
+### Usage in a component
+
+```tsx
+const { coords } = useGeocode("123 Main St, San Francisco, CA");
+
+{coords && (
+  <MapView
+    center={[coords.lat, coords.lng]}
+    zoom={15}
+    markers={[{ lat: coords.lat, lng: coords.lng, label: "Location" }]}
+  />
+)}
+```
+
+---
+
+## Batch geocoding for lists
+
+When geocoding multiple addresses (e.g. search results → map markers), use `Promise.all` with the built-in concurrency limiter:
+
+```ts
+const results = await Promise.all(
+  addresses.map(({ id, address }) =>
+    geocodeAddress(address).then((coords) =>
+      coords ? { id, lat: coords.lat, lng: coords.lng } : null
+    )
+  )
+);
+const markers = results.filter(Boolean);
+```
+
+The `MAX_CONCURRENT` semaphore in the utility ensures no more than 6 requests are in flight, even if you pass 50 addresses.
+
+---
+
+## Hook for multi-marker geocoding
+
+```ts
+import { useState, useEffect } from "react";
+import { geocodeAddress } from "@/utils/geocode";
+import type { MapMarker } from "@/components/MapView";
+
+export function useMapMarkers(
+  items: Array<{ id: string; address: string; label?: string }>
+): { markers: MapMarker[]; loading: boolean } {
+  const [markers, setMarkers] = useState<MapMarker[]>([]);
+  const [loading, setLoading] = useState(false);
+
+  const key = items.map((i) => i.id).join(",");
+
+  useEffect(() => {
+    if (items.length === 0) {
+      setMarkers([]);
+      return;
+    }
+    let cancelled = false;
+    setLoading(true);
+    Promise.all(
+      items.map((item) =>
+        geocodeAddress(item.address).then((coords) =>
+          coords ? { lat: coords.lat, lng: coords.lng, label: item.label ?? item.address } : null
+        )
+      )
+    )
+      .then((results) => {
+        if (!cancelled) setMarkers(results.filter(Boolean) as MapMarker[]);
+      })
+      .catch(() => {
+        if (!cancelled) setMarkers([]);
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [key]);
+
+  return { markers, loading };
+}
+```
+
+---
+
+## CSP considerations
+
+If CSP is enforced, add Nominatim to `connect-src`:
+
+```
+connect-src 'self' https://nominatim.openstreetmap.org;
+```
+
+---
+
+## Alternative geocoding providers
+
+| Provider | Free tier | API key | Notes |
+|----------|-----------|---------|-------|
+| Nominatim (OSM) | Unlimited (rate-limited) | No | Best for prototypes and low-traffic apps |
+| Google Geocoding API | 200 USD/month credit | Yes | Most accurate; requires billing account |
+| Mapbox Geocoding | 100K req/month | Yes | Good accuracy; JS SDK available |
+| LocationIQ | 5K req/day | Yes | Nominatim-compatible API |
+
+For production apps with high traffic, consider Google or Mapbox with an API key and server-side geocoding.