@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental 1.109.8 → 1.110.0

package/dist/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.110.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.109.9...v1.110.0) (2026-03-19)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
+## [1.109.9](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.109.8...v1.109.9) (2026-03-19)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
 ## [1.109.8](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.109.7...v1.109.8) (2026-03-19)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

package/dist/force-app/main/default/webapplications/feature-react-agentforce-conversation-client/package.json

@@ -15,8 +15,8 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/sdk-data": "^1.109.8",
-    "@salesforce/webapp-experimental": "^1.109.8",
+    "@salesforce/sdk-data": "^1.110.0",
+    "@salesforce/webapp-experimental": "^1.110.0",
     "@tailwindcss/vite": "^4.1.17",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -42,7 +42,7 @@
     "@graphql-eslint/eslint-plugin": "^4.1.0",
     "@graphql-tools/utils": "^11.0.0",
     "@playwright/test": "^1.49.0",
-    "@salesforce/vite-plugin-webapp-experimental": "^1.109.8",
+    "@salesforce/vite-plugin-webapp-experimental": "^1.110.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/dist/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.109.8",
+  "version": "1.110.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-      "version": "1.109.8",
+      "version": "1.110.0",
       "license": "SEE LICENSE IN LICENSE.txt",
       "devDependencies": {
         "@lwc/eslint-plugin-lwc": "^3.3.0",

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.109.8",
+  "version": "1.110.0",
   "description": "Base SFDX project template",
   "license": "SEE LICENSE IN LICENSE.txt",
   "publishConfig": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental",
-  "version": "1.109.8",
+  "version": "1.110.0",
   "description": "Embedded Agentforce conversation client feature for web applications",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",
@@ -27,7 +27,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@salesforce/agentforce-conversation-client": "^1.109.8"
+    "@salesforce/agentforce-conversation-client": "^1.110.0"
   },
   "devDependencies": {
     "@types/react": "^19.2.7",

package/dist/.a4drules/skills/building-interactive-map/SKILL.md

@@ -1,92 +0,0 @@
----
-name: building-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/building-interactive-map/implementation/geocoding.md

@@ -1,245 +0,0 @@
-# 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/dist/.a4drules/skills/building-interactive-map/implementation/leaflet-map.md

@@ -1,279 +0,0 @@
-# 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/building-weather-widget/SKILL.md

@@ -1,65 +0,0 @@
----
-name: building-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 `building-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/building-weather-widget/implementation/weather-hook.md

@@ -1,258 +0,0 @@
-# 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/dist/.a4drules/skills/building-weather-widget/implementation/weather-ui.md

@@ -1,216 +0,0 @@
-# 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.