@salesforce/templates 66.3.2 → 66.4.0

package/lib/templates/project/reactb2e/_r_/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;
+```

package/lib/templates/project/reactb2e/_r_/skills/webapp-react-weather-widget/implementation/weather-ui.md

@@ -0,0 +1,216 @@
+# Weather UI — Implementation Guide
+
+## Weather card component
+
+Render the weather data inside a Card component:
+
+```tsx
+import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
+import { useWeather } from "@/hooks/useWeather";
+
+interface WeatherCardProps {
+  lat?: number;
+  lng?: number;
+}
+
+export default function WeatherCard({ lat, lng }: WeatherCardProps) {
+  const { data: weather, loading, error } = useWeather(lat, lng);
+
+  return (
+    <Card className="rounded-2xl shadow-md">
+      <CardHeader>
+        <CardTitle className="text-primary">Weather</CardTitle>
+        <p className="text-sm text-muted-foreground">
+          {new Date().toLocaleDateString("en-US", {
+            weekday: "short",
+            month: "short",
+            day: "numeric",
+            year: "numeric",
+          })}
+        </p>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        {loading && <p className="text-sm text-muted-foreground">Loading weather…</p>}
+        {error && (
+          <p className="text-sm text-destructive" role="alert">
+            {error}
+          </p>
+        )}
+        {!loading && !error && weather && (
+          <>
+            {/* Current conditions */}
+            <p className="text-base text-foreground">{weather.current.description}</p>
+            <p className="text-4xl font-bold text-foreground">{weather.current.tempF}°F</p>
+            <div className="flex flex-wrap gap-4 text-sm text-muted-foreground">
+              <span>{weather.current.windSpeedMph} mph Wind</span>
+              <span>{weather.current.humidity}% Humidity</span>
+            </div>
+
+            {/* Tab indicator */}
+            <div className="flex gap-2 border-b border-border pb-2">
+              <span className="border-b-2 border-primary pb-1 text-sm font-semibold text-primary">
+                Today
+              </span>
+            </div>
+
+            {/* Hourly forecast */}
+            {weather.hourly.length > 0 && (
+              <div className="flex flex-wrap gap-4">
+                {weather.hourly.map((h) => (
+                  <div key={h.time} className="min-w-[60px] rounded-xl bg-muted/50 p-2 text-center">
+                    <p className="text-xs text-muted-foreground">{h.time}</p>
+                    <p className="text-base font-semibold text-foreground">{h.tempF}°</p>
+                  </div>
+                ))}
+              </div>
+            )}
+          </>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+---
+
+## Layout placement
+
+### Dashboard sidebar
+
+Place the weather card in a two-column grid alongside other dashboard content:
+
+```tsx
+<div className="grid grid-cols-1 gap-6 md:grid-cols-2">
+  <div className="space-y-6">
+    {/* Primary dashboard content */}
+  </div>
+  <div>
+    <WeatherCard />
+  </div>
+</div>
+```
+
+### Full-width widget
+
+For a standalone weather section:
+
+```tsx
+<section className="mx-auto max-w-md">
+  <WeatherCard />
+</section>
+```
+
+---
+
+## Loading state
+
+Show a text indicator while data is fetching:
+
+```tsx
+{loading && <p className="text-sm text-muted-foreground">Loading weather…</p>}
+```
+
+For a richer skeleton:
+
+```tsx
+{loading && (
+  <div className="space-y-3">
+    <div className="h-4 w-24 animate-pulse rounded bg-muted" />
+    <div className="h-10 w-16 animate-pulse rounded bg-muted" />
+    <div className="flex gap-4">
+      <div className="h-4 w-20 animate-pulse rounded bg-muted" />
+      <div className="h-4 w-20 animate-pulse rounded bg-muted" />
+    </div>
+  </div>
+)}
+```
+
+---
+
+## Error state
+
+Show error messages with proper ARIA:
+
+```tsx
+{error && (
+  <p className="text-sm text-destructive" role="alert">
+    {error}
+  </p>
+)}
+```
+
+---
+
+## Extending to daily forecast
+
+To show a multi-day forecast, update the `fetchWeather` function to request daily data:
+
+```ts
+url.searchParams.set("daily", "weather_code,temperature_2m_max,temperature_2m_min");
+url.searchParams.set("forecast_days", "7");
+```
+
+Then render each day:
+
+```tsx
+{weather.daily.map((day) => (
+  <div key={day.date} className="flex items-center justify-between rounded-lg bg-muted/50 px-3 py-2">
+    <span className="text-sm text-muted-foreground">{day.dayName}</span>
+    <span className="text-sm font-medium">{day.highF}° / {day.lowF}°</span>
+    <span className="text-xs text-muted-foreground">{day.description}</span>
+  </div>
+))}
+```
+
+---
+
+## Using browser geolocation
+
+To auto-detect the user's location:
+
+```ts
+import { useState, useEffect } from "react";
+
+export function useUserLocation(): { lat: number | null; lng: number | null; error: string | null } {
+  const [lat, setLat] = useState<number | null>(null);
+  const [lng, setLng] = useState<number | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!navigator.geolocation) {
+      setError("Geolocation not supported");
+      return;
+    }
+    navigator.geolocation.getCurrentPosition(
+      (pos) => {
+        setLat(pos.coords.latitude);
+        setLng(pos.coords.longitude);
+      },
+      (err) => {
+        setError(err.message);
+      }
+    );
+  }, []);
+
+  return { lat, lng, error };
+}
+```
+
+Combine with the weather hook:
+
+```tsx
+const { lat, lng } = useUserLocation();
+const { data: weather } = useWeather(lat, lng);
+```
+
+Falls back to the default location if geolocation is denied or unavailable.
+
+---
+
+## Accessibility
+
+- Error messages use `role="alert"` for screen reader announcement.
+- Temperature values include the unit symbol (`°F` or `°C`) in the text.
+- Hourly forecast items are visually distinct with background color and spacing.
+- Loading state provides text feedback, not just spinners.