@salesforce/templates 66.3.2 → 66.4.0

package/lib/templates/project/reactb2e/_r_/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.

package/lib/templates/project/reactb2e/_r_/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/lib/templates/project/reactb2e/_r_/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.