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

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

@@ -0,0 +1,279 @@
+# Leaflet Map — Implementation Guide
+
+## Dependencies
+
+Add to the project:
+
+```bash
+npm install leaflet react-leaflet
+npm install -D @types/leaflet
+```
+
+Import the Leaflet CSS in the component file (not in global CSS — keeps it co-located):
+
+```tsx
+import "leaflet/dist/leaflet.css";
+```
+
+---
+
+## TypeScript declaration (if @types/leaflet is unavailable)
+
+If the project cannot install `@types/leaflet`, create a declaration file:
+
+```ts
+// types/leaflet.d.ts
+declare module "leaflet" {
+  const L: unknown;
+  export default L;
+}
+declare module "leaflet/dist/leaflet.css";
+```
+
+---
+
+## Reusable map component
+
+Create a generic map component at `components/MapView.tsx` (or similar):
+
+```tsx
+import { useMemo, useState, useEffect } from "react";
+import { MapContainer, TileLayer, Marker, Popup, useMap } from "react-leaflet";
+import L from "leaflet";
+import "leaflet/dist/leaflet.css";
+
+const Leaflet = L as {
+  divIcon: (opts: {
+    className?: string;
+    html?: string;
+    iconSize?: [number, number];
+    iconAnchor?: [number, number];
+    popupAnchor?: [number, number];
+  }) => unknown;
+};
+
+const pinIcon = Leaflet.divIcon({
+  className: "map-pin",
+  html: `<span class="map-pin-shape" aria-hidden="true"></span>`,
+  iconSize: [28, 40],
+  iconAnchor: [14, 40],
+  popupAnchor: [0, -40],
+});
+
+export interface MapMarker {
+  lat: number;
+  lng: number;
+  label?: string;
+}
+
+interface MapViewProps {
+  center: [number, number];
+  zoom?: number;
+  markers?: MapMarker[];
+  className?: string;
+}
+
+function MapCenterUpdater({ center, zoom = 13 }: { center: [number, number]; zoom?: number }) {
+  const map = useMap() as { setView: (center: [number, number], zoom: number) => void };
+  useEffect(() => {
+    map.setView(center, zoom);
+  }, [map, center[0], center[1], zoom]);
+  return null;
+}
+
+export default function MapView({
+  center,
+  zoom = 13,
+  markers = [],
+  className = "h-[400px] w-full rounded-xl overflow-hidden",
+}: MapViewProps) {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  const effectiveCenter = useMemo((): [number, number] => {
+    if (markers.length > 0) {
+      const sum = markers.reduce((acc, m) => [acc[0] + m.lat, acc[1] + m.lng], [0, 0]);
+      return [sum[0] / markers.length, sum[1] / markers.length];
+    }
+    return center;
+  }, [center, markers]);
+
+  if (!mounted || typeof window === "undefined") {
+    return (
+      <div
+        className={className + " bg-muted flex items-center justify-center text-muted-foreground text-sm"}
+        aria-hidden
+      >
+        Loading map…
+      </div>
+    );
+  }
+
+  return (
+    <div className={className} aria-label="Map">
+      <MapContainer
+        center={effectiveCenter}
+        zoom={zoom}
+        scrollWheelZoom
+        className="h-full w-full"
+        style={{ minHeight: 200 }}
+      >
+        <MapCenterUpdater center={effectiveCenter} zoom={zoom} />
+        <TileLayer
+          attribution='Data by &copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>'
+          url="https://tile.openstreetmap.org/{z}/{x}/{y}.png"
+          maxZoom={19}
+        />
+        {markers.map((m, i) => (
+          <Marker key={`${m.lat}-${m.lng}-${i}`} position={[m.lat, m.lng]} icon={pinIcon}>
+            <Popup>{m.label ?? "Location"}</Popup>
+          </Marker>
+        ))}
+      </MapContainer>
+    </div>
+  );
+}
+```
+
+---
+
+## Tile provider: OpenStreetMap
+
+The default tile URL is free and requires no API key:
+
+```
+https://tile.openstreetmap.org/{z}/{x}/{y}.png
+```
+
+| Property | Value |
+|----------|-------|
+| Cost | Free |
+| API key | None |
+| Max zoom | 19 |
+| Attribution | Required — `© OpenStreetMap` |
+
+CSP `img-src` must include `https://tile.openstreetmap.org` if CSP is enforced.
+
+---
+
+## Custom pin icon via CSS
+
+The `divIcon` approach avoids external marker image dependencies. Add these styles to your global CSS or a co-located CSS file:
+
+```css
+.map-pin {
+  background: transparent !important;
+  border: none !important;
+}
+
+.map-pin-shape {
+  display: block;
+  width: 28px;
+  height: 40px;
+  background: hsl(var(--primary));
+  border-radius: 50% 50% 50% 0;
+  transform: rotate(-45deg);
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
+}
+
+.map-pin-shape::after {
+  content: "";
+  display: block;
+  width: 12px;
+  height: 12px;
+  background: white;
+  border-radius: 50%;
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+}
+```
+
+---
+
+## SSR safety
+
+Leaflet requires `window` and `document`. The component guards against SSR with:
+
+1. A `mounted` state that only becomes `true` in `useEffect` (client-side).
+2. A `typeof window === "undefined"` check.
+3. A loading placeholder rendered during SSR / before mount.
+
+This prevents "window is not defined" errors in SSR or static builds.
+
+---
+
+## MapCenterUpdater pattern
+
+`react-leaflet`'s `MapContainer` does not re-center when the `center` prop changes after initial render. The `MapCenterUpdater` child component uses `useMap()` to call `map.setView()` reactively:
+
+```tsx
+function MapCenterUpdater({ center, zoom = 13 }: { center: [number, number]; zoom?: number }) {
+  const map = useMap();
+  useEffect(() => {
+    map.setView(center, zoom);
+  }, [map, center[0], center[1], zoom]);
+  return null;
+}
+```
+
+Place it as a direct child of `<MapContainer>`.
+
+---
+
+## Multi-marker center calculation
+
+When rendering multiple markers, auto-center the map on their centroid:
+
+```tsx
+const effectiveCenter = useMemo((): [number, number] => {
+  if (markers.length > 0) {
+    const sum = markers.reduce((acc, m) => [acc[0] + m.lat, acc[1] + m.lng], [0, 0]);
+    return [sum[0] / markers.length, sum[1] / markers.length];
+  }
+  return fallbackCenter;
+}, [markers, fallbackCenter]);
+```
+
+---
+
+## Split-panel layout (map + list)
+
+For a search page with map on the left and scrollable results on the right:
+
+```tsx
+<div className="flex h-[calc(100vh-4rem)] min-h-[500px] flex-col">
+  {/* Search bar */}
+  <div className="shrink-0 border-b bg-background px-4 py-3">
+    {/* search input */}
+  </div>
+  {/* Map + List */}
+  <div className="flex min-h-0 flex-1 flex-col lg:flex-row">
+    <div className="h-64 shrink-0 lg:h-full lg:min-h-0 lg:w-2/3" aria-label="Map">
+      <MapView center={center} markers={markers} className="h-full w-full" />
+    </div>
+    <aside className="flex w-full flex-col border-t lg:w-1/3 lg:border-l lg:border-t-0">
+      <div className="flex-1 overflow-y-auto p-4">
+        {/* list items */}
+      </div>
+    </aside>
+  </div>
+</div>
+```
+
+Key points:
+- `h-[calc(100vh-4rem)]` fills viewport minus header.
+- `lg:flex-row` stacks vertically on mobile, side-by-side on desktop.
+- List panel uses `overflow-y-auto` for independent scrolling.
+
+---
+
+## Accessibility
+
+- Wrap the map `<div>` with `aria-label="Map"` or a descriptive label.
+- Pin icon inner HTML uses `aria-hidden="true"`.
+- Popups contain text labels for each marker.
+- Provide a text-based alternative (address list) for screen readers.

package/dist/.a4drules/skills/webapp-react-weather-widget/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: webapp-react-weather-widget
+description: Adds a weather widget to React pages using the free Open-Meteo API. Use when the user asks to add weather, show a forecast, display current conditions, add a weather card, or integrate weather data into the web application.
+---
+
+# Weather Widget
+
+## When to Use
+
+Use this skill when:
+- Adding current weather conditions to a dashboard or sidebar
+- Displaying an hourly or daily forecast
+- Showing location-based weather for a property, event, or destination
+
+---
+
+## Step 1 — Determine widget scope
+
+Identify what weather data the user needs:
+
+- **Current conditions only** — temperature, description, wind, humidity
+- **Current + hourly forecast** — conditions + next 6–12 hours
+- **Current + daily forecast** — conditions + multi-day outlook
+
+If unclear, ask:
+
+> "Should the weather widget show just current conditions, or include an hourly/daily forecast too?"
+
+---
+
+## Step 2 — Determine location source
+
+The widget needs a latitude/longitude. Identify where this comes from:
+
+- **Fixed default** — hardcoded city (e.g. San Francisco: `37.7749, -122.4194`)
+- **User's location** — browser Geolocation API
+- **Address-based** — geocode an address to lat/lng (see the `webapp-react-interactive-map` skill for geocoding)
+- **Prop-driven** — parent component passes lat/lng
+
+---
+
+## Step 3 — Implementation
+
+Read the corresponding guides:
+
+- **Weather data hook** — read `implementation/weather-hook.md` for the `useWeather` custom hook and Open-Meteo API integration.
+- **Weather UI component** — read `implementation/weather-ui.md` for rendering weather data in a card.
+
+---
+
+## Verification
+
+Before completing:
+
+1. Widget shows real weather data (not mocked).
+2. Loading and error states are handled gracefully.
+3. Temperature displays in the correct unit (°F or °C).
+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.

package/dist/.a4drules/skills/webapp-react-weather-widget/implementation/weather-hook.md

@@ -0,0 +1,258 @@
+# Weather Hook — Implementation Guide
+
+## Recommended API: Open-Meteo
+
+| Property | Value |
+|----------|-------|
+| Endpoint | `https://api.open-meteo.com/v1/forecast` |
+| Cost | Free for non-commercial use; no signup |
+| API key | **None required** |
+| Rate limit | 10,000 requests/day |
+| Data | Current conditions, hourly, daily, historical |
+| Weather codes | WMO standard codes |
+
+### Why Open-Meteo over alternatives
+
+| Provider | API key | Free tier | Notes |
+|----------|---------|-----------|-------|
+| **Open-Meteo** | No | 10K/day | Best for prototypes and low-traffic; no auth required |
+| OpenWeatherMap | Yes | 1K calls/day | Popular but requires signup and API key |
+| WeatherAPI.com | Yes | 1M calls/month | Good free tier but requires key management |
+| Visual Crossing | Yes | 1K calls/day | Historical data strength |
+
+Open-Meteo is the default choice because it requires zero configuration.
+
+---
+
+## WMO weather codes
+
+Open-Meteo returns standard WMO weather codes. Map them to human-readable labels:
+
+```ts
+const WEATHER_LABELS: Record<number, string> = {
+  0: "Clear",
+  1: "Mainly clear",
+  2: "Partly cloudy",
+  3: "Overcast",
+  45: "Foggy",
+  48: "Depositing rime fog",
+  51: "Light drizzle",
+  53: "Drizzle",
+  55: "Dense drizzle",
+  61: "Slight rain",
+  63: "Rain",
+  65: "Heavy rain",
+  71: "Slight snow",
+  73: "Snow",
+  75: "Heavy snow",
+  77: "Snow grains",
+  80: "Slight rain showers",
+  81: "Rain showers",
+  82: "Heavy rain showers",
+  85: "Slight snow showers",
+  86: "Heavy snow showers",
+  95: "Thunderstorm",
+  96: "Thunderstorm + hail",
+  99: "Thunderstorm + heavy hail",
+};
+
+function weatherLabel(code: number): string {
+  return WEATHER_LABELS[code] ?? "Unknown";
+}
+```
+
+---
+
+## Temperature conversion
+
+Open-Meteo returns Celsius by default. Convert to Fahrenheit when needed:
+
+```ts
+function celsiusToFahrenheit(c: number): number {
+  return Math.round((c * 9) / 5 + 32);
+}
+```
+
+Alternatively, request Fahrenheit directly via `&temperature_unit=fahrenheit` in the query string.
+
+---
+
+## TypeScript interfaces
+
+```ts
+export interface WeatherCurrent {
+  description: string;
+  tempF: number;
+  humidity: number;
+  windSpeedKmh: number;
+  windSpeedMph: number;
+}
+
+export interface WeatherHour {
+  time: string;
+  tempF: number;
+}
+
+export interface WeatherData {
+  current: WeatherCurrent;
+  hourly: WeatherHour[];
+  timezone: string;
+}
+```
+
+---
+
+## The useWeather hook
+
+Create at `hooks/useWeather.ts`:
+
+```ts
+import { useState, useEffect } from "react";
+
+const DEFAULT_LAT = 37.7749;
+const DEFAULT_LNG = -122.4194;
+
+async function fetchWeather(lat: number, lng: number): Promise<WeatherData> {
+  const url = new URL("https://api.open-meteo.com/v1/forecast");
+  url.searchParams.set("latitude", String(lat));
+  url.searchParams.set("longitude", String(lng));
+  url.searchParams.set("current", "temperature_2m,relative_humidity_2m,weather_code,wind_speed_10m");
+  url.searchParams.set("hourly", "temperature_2m");
+  url.searchParams.set("timezone", "auto");
+  url.searchParams.set("forecast_days", "1");
+
+  const res = await fetch(url.toString());
+  if (!res.ok) throw new Error(`Weather API error: ${res.status}`);
+  const data = await res.json();
+
+  const cur = data.current ?? {};
+  const tempC = cur.temperature_2m ?? 0;
+  const humidity = cur.relative_humidity_2m ?? 0;
+  const windKmh = cur.wind_speed_10m ?? 0;
+  const windMph = Math.round(windKmh * 0.621371 * 10) / 10;
+  const code = cur.weather_code ?? 0;
+
+  const hourly: WeatherHour[] = [];
+  const times: string[] = data.hourly?.time ?? [];
+  const temps: (number | null)[] = data.hourly?.temperature_2m ?? [];
+  const now = new Date();
+
+  for (let i = 0; i < times.length; i++) {
+    const t = times[i];
+    const temp = temps[i];
+    if (t && temp != null) {
+      const d = new Date(t);
+      if (d >= now) {
+        hourly.push({
+          time: d.toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit", hour12: true }),
+          tempF: celsiusToFahrenheit(temp),
+        });
+      }
+    }
+    if (hourly.length >= 6) break;
+  }
+
+  return {
+    current: {
+      description: weatherLabel(code),
+      tempF: celsiusToFahrenheit(tempC),
+      humidity,
+      windSpeedKmh: windKmh,
+      windSpeedMph: windMph,
+    },
+    hourly,
+    timezone: data.timezone ?? "auto",
+  };
+}
+
+export function useWeather(lat?: number | null, lng?: number | null) {
+  const latitude = lat ?? DEFAULT_LAT;
+  const longitude = lng ?? DEFAULT_LNG;
+
+  const [data, setData] = useState<WeatherData | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    fetchWeather(latitude, longitude)
+      .then((d) => {
+        if (!cancelled) setData(d);
+      })
+      .catch((e) => {
+        if (!cancelled) setError(e instanceof Error ? e.message : "Failed to load weather");
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [latitude, longitude]);
+
+  return { data, loading, error };
+}
+```
+
+### Hook design patterns
+
+| Pattern | Why |
+|---------|-----|
+| Cancellation flag (`cancelled`) | Prevents state updates on unmounted components |
+| Default coordinates | Widget works immediately without user location |
+| Dependency array `[latitude, longitude]` | Re-fetches only when location changes |
+| Separate `loading` and `error` states | Enables distinct UI for each state |
+
+---
+
+## Open-Meteo API parameters reference
+
+### Current weather variables
+
+| Variable | Description |
+|----------|-------------|
+| `temperature_2m` | Air temperature at 2m height (°C) |
+| `relative_humidity_2m` | Relative humidity (%) |
+| `weather_code` | WMO weather code |
+| `wind_speed_10m` | Wind speed at 10m height (km/h) |
+| `apparent_temperature` | Feels-like temperature (°C) |
+| `precipitation` | Precipitation sum (mm) |
+
+### Hourly variables
+
+| Variable | Description |
+|----------|-------------|
+| `temperature_2m` | Temperature each hour |
+| `precipitation_probability` | Chance of rain (%) |
+| `weather_code` | Condition each hour |
+
+### Daily variables
+
+| Variable | Description |
+|----------|-------------|
+| `temperature_2m_max` | Daily high |
+| `temperature_2m_min` | Daily low |
+| `weather_code` | Dominant condition |
+| `sunrise` | Sunrise time (ISO) |
+| `sunset` | Sunset time (ISO) |
+
+### Useful query parameters
+
+| Param | Example | Purpose |
+|-------|---------|---------|
+| `timezone` | `auto` or `America/Los_Angeles` | Localizes times |
+| `forecast_days` | `1`–`16` | Number of days |
+| `temperature_unit` | `fahrenheit` | Direct °F responses |
+| `wind_speed_unit` | `mph` | Direct mph responses |
+
+---
+
+## CSP considerations
+
+If CSP is enforced, add Open-Meteo to `connect-src`:
+
+```
+connect-src 'self' https://api.open-meteo.com;
+```