@schandlergarcia/sf-web-components 1.9.76 → 1.9.77

package/.a4drules/skills/command-center-builder/SKILL.md

@@ -13,6 +13,8 @@ description: >-
 
 These rules apply when building dashboards rendered by `CommandCenter.tsx`. For full component API details, read the **component-library** skill.
 
+> **BUILD GUIDE:** The dashboard is built in 3 phases. Read [`getting-started.md`](getting-started.md) for what to build (and what to skip) in each phase. Do NOT build ahead — only build what the current phase asks for.
+
 ## WIRING — DO THIS FIRST (before building the dashboard)
 
 **Building a dashboard requires updating 4 files. If you only create the dashboard file, the user will never see it — they'll see the old Account Search page instead.**

package/.a4drules/skills/command-center-builder/getting-started.md

@@ -1 +1,98 @@
-See SKILL.md — Core Conventions, Library Components, Images, Navigation sections.
+# Engine Travel Command Center — Build Guide
+
+The dashboard is built in **3 phases**, one per user prompt. Each phase adds a layer. Do NOT build ahead — only build what the current phase asks for.
+
+---
+
+## Phase 1 — Build the Dashboard (sample data only)
+
+**What to build:**
+- `src/pages/EngineDashboard.tsx` with:
+  - Sticky header (h-12, Engine logo, "Travel Command Center", "Powered by Agentforce" badge, bell icon, theme toggle)
+  - Hero GeoMap (h-[520px]) with markers, arcs, overlays from sample data
+  - Glass KPI overlays on the map (Active Travelers, Spend MTD, Compliance %, Eva Resolved)
+  - Flight status strip (horizontal scroll, glass pills)
+  - Escalations panel (BaseCard with "Assign to Agent" buttons, toast on click)
+  - Disruptions panel (severity dots, flight info, Eva action lines)
+  - Active Travelers panel (expandable cards with Avatar, details grid, "View in Salesforce" links)
+  - Monthly Spend chart (ChartCard + D3Chart groupedBarChart)
+- All data from `src/data/engine-sample-data.js` via `useDataSource({ sample: SAMPLE_DATA, live: [] })`
+- Brand tokens in `global.css`
+
+**What to wire:**
+- `CommandCenter.tsx` → import EngineDashboard
+- `Home.tsx` → REPLACE with CommandCenter wrapper
+- `routes.tsx` → Home as index route with label "Dashboard"
+
+**What NOT to build (saved for later phases):**
+- No ChatBar or Eva AI chat — that's Phase 3
+- No AgentforceConversationClient — that's Phase 3
+- No `useEngineLiveData` or live data wiring — that's Phase 2
+- No Salesforce metadata (custom fields, platform events, Apex) — that's Phases 2-3
+- Leave `live:` props empty (`live: []` or `live: undefined`) — Phase 2 fills them in
+
+---
+
+## Phase 2 — Connect to Live Data
+
+**What to build:**
+- Import `useEngineLiveData` from `src/hooks/useEngineLiveData.ts`
+- Wire `live` prop on every `useDataSource` call:
+  ```tsx
+  const live = useEngineLiveData();
+  const markers = useDataSource({ sample: MAP_MARKERS, live: live.mapMarkers });
+  const arcs = useDataSource({ sample: MAP_ARCS, live: live.mapArcs });
+  ```
+- Update KPI overlays to use active metrics:
+  ```tsx
+  const activeMetrics = live.loading ? METRICS : live.metrics;
+  ```
+
+**What to do after wiring:**
+- Proactively suggest creating `Flight__c.Weather_Impact__c` custom field
+- If confirmed, create SFDX XML from PRD section 14a and deploy
+
+**What NOT to build:**
+- No ChatBar or Eva — that's Phase 3
+- No platform events or Apex — that's Phase 3
+
+---
+
+## Phase 3 — Add Agentforce
+
+**What to build:**
+- `ChatBar` between the map and data panels:
+  ```tsx
+  <div className="px-4 pt-4">
+    <ChatBar
+      title="Eva"
+      placeholder="Ask Eva anything about travelers, bookings, policy, or spend…"
+      suggestions={CHAT_SUGGESTIONS}
+      onSend={handleChat}
+    />
+  </div>
+  ```
+- Suggestions: weather warning, rebooking policy, notify travelers, create support case
+- `handleChat` mock response at module scope
+- `AgentforceConversationClient` with `agentId="0Xxa5000000relhCAA"` and `agentLabel="Eva"`
+
+**What to do after adding Eva:**
+- Proactively suggest creating `Travel_Disruption_Alert__e` platform event
+- If confirmed, create SFDX XML from PRD section 14b and deploy
+- Then suggest creating `TravelDisruptionEventService` Apex class
+- If confirmed, create from PRD section 14c and deploy
+
+---
+
+## Phase Summary
+
+| | Phase 1 | Phase 2 | Phase 3 |
+|---|---------|---------|---------|
+| Dashboard layout & panels | Build | — | — |
+| Sample data | Wire | — | — |
+| Live data | Skip | Wire | — |
+| Custom field metadata | Skip | Suggest | — |
+| ChatBar (Eva) | Skip | Skip | Build |
+| AgentforceConversationClient | Skip | Skip | Build |
+| Platform event | Skip | Skip | Suggest |
+| Apex service | Skip | Skip | Suggest |

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.77] - 2026-04-04
+
+### Added
+- **Three-phase build guide (`getting-started.md`)** — Replaced one-liner pointer with a full phase-by-phase guide telling the agent exactly what to build and what to skip in each phase. Includes code snippets, explicit "NOT in this phase" callouts, and a summary table
+- **Build guide callout in SKILL.md** — Added a prominent callout at the top of the builder skill pointing to the build guide so agents see it immediately
+
+**Context:** Agent was building everything (including Eva ChatBar) in Phase 1 because there was no guide telling it to stop. The PRD had phase instructions but nothing in the skills enforced it. Now `getting-started.md` defines exactly what belongs in each of the 3 phases.
+
 ## [1.9.76] - 2026-04-04
 
 ### Fixed

package/data/engine-command-center-prd.md

@@ -326,7 +326,7 @@ Build incrementally in 3 prompts. Each prompt builds on the previous result. The
 
 ### Prompt 1 — Build the Dashboard
 
-> Build me a travel command center for Engine. There's a PRD with the full spec. I want the big hero map showing where all our travelers are with flight arcs, glass KPI overlays on top of the map, a flight status ticker, and then below that the main panels — escalations that need attention, active disruptions, our traveler roster with expandable details, and a spend trend chart. Hook it all up to the sample data so it looks real. Make it the home page when you're done — I want to see it when I open the app.
+> Build me a travel command center for Engine. There's a PRD with the full spec. I want the big hero map showing where all our travelers are with flight arcs, glass KPI overlays on top of the map, a flight status ticker, and then below that the main panels — escalations that need attention, active disruptions, our traveler roster with expandable details, and a spend trend chart. Hook it all up to the sample data so it looks real. Don't worry about the AI assistant or live data yet — we'll layer those on after. Make it the home page when you're done — I want to see it when I open the app.
 
 **What the agent must do:**
 
@@ -337,6 +337,11 @@ Build incrementally in 3 prompts. Each prompt builds on the previous result. The
 5. **Update `src/routes.tsx`** to set Home as the index route with label "Dashboard"
 6. Add Engine brand tokens to `global.css` if not already present
 
+**What the agent must NOT do in this prompt:**
+- Do NOT add the ChatBar or any Eva/Agentforce integration — that's Prompt 3
+- Do NOT wire up live data or `useEngineLiveData` — that's Prompt 2
+- Do NOT create Salesforce metadata (custom fields, platform events, Apex) — that's Prompts 2 and 3
+
 **Common failure:** The agent creates the dashboard file but forgets to update `Home.tsx` and `routes.tsx`, so the user still sees the Account Search page. The wiring section at the top of `.a4drules/skills/command-center-builder/SKILL.md` explains all required file changes.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schandlergarcia/sf-web-components",
-  "version": "1.9.76",
+  "version": "1.9.77",
   "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
   "type": "module",
   "main": "./dist/index.js",