@schandlergarcia/sf-web-components 1.9.63 → 1.9.64

package/.a4drules/phases/phase-4-agent.md

@@ -0,0 +1,73 @@
+---
+name: engine-phase-4-agent
+description: >-
+  Phase 4 of the Engine Travel Command Center build. Adds Eva ChatBar to the
+  header and Salesforce signals throughout the dashboard.
+  Use this when the build prompt says "Phase 4" or "agent".
+---
+
+# Phase 4: Agentforce Integration
+
+**Source of truth:** `engine-command-center-prd.md` (sections 9–10)
+
+**Goal:** Add Eva as a ChatBar in the header. Add subtle Salesforce signals throughout the dashboard.
+
+## Eva — ChatBar in header
+
+Eva surfaces as a `ChatBar` in the header. Not a FAB. Not a sliding panel. Not a `ChatPanel` in the grid.
+
+### Code
+
+Define the handler and suggestions at **module scope** (outside the component):
+
+```tsx
+import { ChatBar } from "@/components/library";
+
+const CHAT_SUGGESTIONS = [
+  "Who's traveling internationally right now?",
+  "Show bookings pending approval",
+  "What has Eva resolved today?",
+  "Travelers returning this week",
+];
+
+function handleChat(message: string) {
+  // Agentforce integration or mock response
+  return {
+    text: `Eva is looking into: "${message}"`,
+    components: [],
+  };
+}
+```
+
+Add the ChatBar to the header (right side, before the notification bell):
+
+```tsx
+<ChatBar
+  title="Eva"
+  placeholder="Ask about travelers, bookings, policy, spend…"
+  suggestions={CHAT_SUGGESTIONS}
+  onSend={handleChat}
+/>
+```
+
+### Agent responses
+
+Return structured `components` arrays for data (MetricCard, DataTable, StatusCard) — never markdown tables in text content.
+
+## Salesforce Signals
+
+Subtle, contextual indicators — like "Sent from iPhone", not promotional banners.
+
+| Signal | Location | Implementation |
+|--------|----------|----------------|
+| "View in Salesforce" | Traveler expanded view, booking rows | Micro-link, muted text (`text-slate-400`) |
+| "Salesforce updated" | After rebook/approve actions | `toast()` with success tone |
+| "Powered by Agentforce" | ChatBar subtitle area | Small badge/chip |
+
+## Constraints (5 only)
+
+1. ChatBar goes in the **header**, not as a floating panel or grid element
+2. `CHAT_SUGGESTIONS` and `handleChat` defined at **module scope** (outside component body)
+3. Salesforce signals are subtle micro-text — not banners or badges
+4. Import ONLY from `@/components/library` and `@heroicons/react`
+5. DO NOT run `npm run dev` or `npm run validate:dashboard`

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

@@ -254,7 +254,9 @@ Every dashboard needs a unique layout structure and at least one domain-specific
 
 ## Map Layout
 
-GeoMap should be placed in a **wide/narrow grid** (`lg:grid-cols-3` with `lg:col-span-2`), not full-width hero. Full-width maps dominate the page and waste space.
+**Default pattern:** GeoMap in a **wide/narrow grid** (`lg:grid-cols-3` with `lg:col-span-2`). This works well for dashboards where the map is one of several equal-weight sections.
+
+**If the PRD specifies a "visualization-hero" layout**, the map is full-width hero with glass overlays. The PRD always overrides this default pattern.
 
 **Pattern: Map + sidebar at matched height**
 
@@ -584,37 +586,11 @@ Before finishing a dashboard page, verify ALL of these:
 - [ ] **Imports only from `@/components/library`** — no shadcn, no Lucide, no `cn()`
 - [ ] **Grid patterns match the approved list** — no custom grid layouts
 
-## Post-Completion Verification (REQUIRED — MUST RUN BEFORE REPORTING DONE)
-
-After building the dashboard, you MUST run the validator and fix ALL errors before reporting the dashboard as complete:
-
-```bash
-# Run from the web app directory
-npm run validate:dashboard
-```
-
-**Do NOT run `npm run build` or `tsc`.** The TypeScript build has known issues with platform-only Salesforce packages that are not relevant to dashboard development. Only run the validator.
-
-The validator (`scripts/validate-dashboard.sh`) automatically checks for:
-- Hand-rolled HTML cards, tables, and SVGs (must use library components)
-- Forbidden colors (`text-black`, `text-white`, `bg-black`)
-- Inline `style={{}}` and `<style>` tags
-- Missing `useDataSource` for sample/live mode
-- Grid layouts with 5+ columns
-- `position: fixed` without `createPortal`
-- shadcn/Lucide imports in command center code
-- Missing `space-y-6` wrappers
-- `.jsx` files where `.tsx` is required (this is a TypeScript project)
-- Dashboard navigation (`<nav>` elements)
-
-**If the validator reports errors, you MUST fix them ALL — zero errors required.** Do not report the dashboard as complete with any errors. Do not dismiss errors as "acceptable", "justified", or "expected". Every error has a fix — usually by switching to the correct library component. The validator exits with code 1 on errors — treat this like a failing test.
+## Post-Completion Verification
 
-**Common validator errors and their fixes:**
-- **Hand-rolled card** → Wrap content in `WidgetCard`, `ListCard`, `BaseCard`, or another library card component. `WidgetCard` with a single section can wrap any arbitrary JSX content.
-- **Forbidden colors** (`text-white`, `bg-black`) → Use slate scale (`text-slate-50`, `bg-slate-900`)
-- **shadcn/Lucide imports** → Replace with library components and Heroicons
+**DO NOT run `npm run validate:dashboard`, `npm run dev`, `npm run build`, or `tsc` during builds.** These waste time and are not required for phase completion.
 
-**Do not skip or ignore the validator.** Do not run `npm run build` or `tsc` — only run `npm run validate:dashboard`.
+Instead, verify correctness by reviewing the code against the Pre-Completion Checklist above. Confirm that all three wiring files are updated (CommandCenter.tsx, Home.tsx, routes.tsx).
 
 ## Anti-Patterns (never do these)
 

package/.a4drules/skills/command-center-builder/completion-checklist.md

@@ -19,37 +19,11 @@ Before finishing a dashboard page, verify ALL of these:
 - [ ] **Imports only from `@/components/library`** — no shadcn, no Lucide, no `cn()`
 - [ ] **Grid patterns match the approved list** — no custom grid layouts
 
-## Post-Completion Verification (REQUIRED — MUST RUN BEFORE REPORTING DONE)
+## Post-Completion Verification
 
-After building the dashboard, you MUST run the validator and fix ALL errors before reporting the dashboard as complete:
+**DO NOT run `npm run validate:dashboard`, `npm run dev`, `npm run build`, or `tsc` during builds.** These waste time and are not required for phase completion.
 
-```bash
-# Run from the web app directory
-npm run validate:dashboard
-```
-
-**Do NOT run `npm run build` or `tsc`.** The TypeScript build has known issues with platform-only Salesforce packages that are not relevant to dashboard development. Only run the validator.
-
-The validator (`scripts/validate-dashboard.sh`) automatically checks for:
-- Hand-rolled HTML cards, tables, and SVGs (must use library components)
-- Forbidden colors (`text-black`, `text-white`, `bg-black`)
-- Inline `style={{}}` and `<style>` tags
-- Missing `useDataSource` for sample/live mode
-- Grid layouts with 5+ columns
-- `position: fixed` without `createPortal`
-- shadcn/Lucide imports in command center code
-- Missing `space-y-6` wrappers
-- `.jsx` files where `.tsx` is required (this is a TypeScript project)
-- Dashboard navigation (`<nav>` elements)
-
-**If the validator reports errors, you MUST fix them ALL — zero errors required.** Do not report the dashboard as complete with any errors. Do not dismiss errors as "acceptable", "justified", or "expected". Every error has a fix — usually by switching to the correct library component. The validator exits with code 1 on errors — treat this like a failing test.
-
-**Common validator errors and their fixes:**
-- **Hand-rolled card** → Wrap content in `WidgetCard`, `ListCard`, `BaseCard`, or another library card component. `WidgetCard` with a single section can wrap any arbitrary JSX content.
-- **Forbidden colors** (`text-white`, `bg-black`) → Use slate scale (`text-slate-50`, `bg-slate-900`)
-- **shadcn/Lucide imports** → Replace with library components and Heroicons
-
-**Do not skip or ignore the validator.** Do not run `npm run build` or `tsc` — only run `npm run validate:dashboard`.
+Instead, verify correctness by reviewing the code against the Pre-Completion Checklist above. Confirm that all three wiring files are updated (CommandCenter.tsx, Home.tsx, routes.tsx).
 
 ## Anti-Patterns (never do these)
 

package/.a4drules/skills/command-center-builder/improved-build-process.md

@@ -1,341 +1,30 @@
-# Improved Dashboard Build Process
+# Dashboard Build Process
 
-## 4-Phase Build Approach
+## 4-Phase Build
 
-Build dashboards in 4 distinct phases with clear separation of concerns:
+Build dashboards in 4 distinct phases. Each phase has a dedicated instruction file with a code template in `.a4drules/phases/`:
 
-### Phase 1: Layout & Structure
-**Goal:** Establish layout, spacing, and component placement
-**Output:** Skeleton with placeholders, no real data or logic
+| Phase | File | Goal | Output |
+|-------|------|------|--------|
+| 1 | `phase-1-layout.md` | Layout & structure | Skeleton with placeholders |
+| 2 | `phase-2-components.md` | Components & sample data | Fully functional UI with mock data |
+| 3 | `phase-3-live-data.md` | Real data integration | Dashboard connected to Salesforce |
+| 4 | `phase-4-agent.md` | Agentforce integration | Eva agent + Salesforce signals |
 
-### Phase 2: Components & Sample Data
-**Goal:** Build all UI components with realistic mock data
-**Output:** Fully functional UI using hardcoded sample data
-
-### Phase 3: Real Data Integration
-**Goal:** Replace sample data with live Salesforce data
-**Output:** Dashboard connected to real data sources
-
-### Phase 4: Agentforce Integration
-**Goal:** Add AI agent capabilities
-**Output:** Eva agent integrated with chat interface
-
----
-
-## Example: Engine Travel Command Center
-
-### Prompt 1 — Layout & Structure
-
-> Load skills: command-center-builder, command-center-project, component-library, outer-app. 
-> Use `docs/engine-command-center-prd.md` as source of truth.
->
-> **Phase 1: Layout Only**
->
-> Scaffold the Engine Travel Command Center structure:
-> 
-> 1. **Header Layout** - Compact dark header with:
->    - Engine logo placeholder (gray box)
->    - Wordmark placeholder
->    - Theme toggle (functional)
->    - Empty space for ChatBar (Phase 4)
->
-> 2. **Hero Section** - Full-width map container:
->    - Empty GeoMap component (no markers, no data)
->    - Placeholder for KPI overlays (gray boxes with labels)
->    - Placeholder for flight status strip (gray bar)
->
-> 3. **Data Panels Grid** - Layout sections with empty cards:
->    - Disruptions panel (left, wide)
->    - Active travelers panel (right, narrow)
->    - Activity feed + chart row
->    - Bookings table section
->    - Policy + spend chart row
->
-> 4. **Theme Setup** - Update brand palette to Engine teal tokens (section 3 PRD)
->
-> 5. **File Structure**:
->    - Create `src/pages/EngineDashboard.tsx`
->    - Wire into `CommandCenter.tsx`
->    - Use placeholder cards: `<BaseCard><div className="h-48 bg-slate-100">Section Name</div></BaseCard>`
->
-> **DO NOT:**
-> - Add any real data or sample data
-> - Build actual components beyond placeholders
-> - Add data fetching logic
-> - Add interactive features beyond theme toggle
->
-> **Deliverable:** A skeleton dashboard with proper layout, spacing, and placeholder cards that shows the structure.
-
----
-
-### Prompt 2 — Components & Sample Data
-
-> Load skills: command-center-builder, command-center-project, component-library.
-> Refer to `docs/engine-command-center-prd.md` sections 7, 8, and 12.
->
-> **Phase 2: Build All Components with Sample Data**
->
-> Replace all placeholders with fully functional components using hardcoded sample data:
->
-> 1. **Create Sample Data File** - `src/data/engine-sample-data.ts`:
->    - Travelers (10 active travelers with names, flights, hotels)
->    - Flights (8 active flights with routes, status, progress %)
->    - Disruptions (3 weather events, 2 delays, 1 cancellation)
->    - Bookings (20 bookings with all fields)
->    - Policy items (5 compliance items with status)
->    - Eva actions (15 recent actions)
->    - Spend history (12 months of data)
->    - Destination stats (top 10 cities)
->
-> 2. **Populate Map** - Wire sample data into GeoMap:
->    - Show markers at origin/destination cities
->    - Draw flight arcs with animated progress dots
->    - Add weather overlays for disrupted areas
->    - Add 4 glass KPI overlays (flights, travelers, disruptions, bookings count)
->    - Add flight status strip with colored status chips
->
-> 3. **Build Disruptions Panel**:
->    - Use ListCard with disruption items
->    - Show severity indicators (red/yellow/blue)
->    - Show affected travelers
->    - Show Eva's actions
->
-> 4. **Build Active Travelers Panel**:
->    - Use ListCard with expandable traveler cards
->    - Click to expand and show flight, hotel, return date
->    - Use Avatar for traveler photos
->    - Show status chips
->
-> 5. **Build Activity Feed + Chart**:
->    - Use FeedPanel for Eva activities
->    - Use ChartCard with bar chart of travelers by destination
->
-> 6. **Build Bookings Table**:
->    - Use TableCard with search, sort, pagination
->    - Show all booking fields from section 12
->    - Add status chips
->
-> 7. **Build Policy + Spend Charts**:
->    - Use StatusCard for policy compliance
->    - Use ChartCard with line chart of monthly spend
->
-> 8. **Add Interactivity**:
->    - Click travelers to expand/collapse
->    - Search/filter bookings table
->    - Sort table columns
->    - Hover map markers for tooltips
->
-> **DO NOT:**
-> - Connect to Salesforce data (use hardcoded data only)
-> - Add data fetching hooks
-> - Add GraphQL queries
-> - Add Agentforce/Eva chat
->
-> **Deliverable:** A fully functional dashboard with all components working using sample data. Everything should look and feel complete, just not connected to live data yet.
-
----
-
-### Prompt 3 — Real Data Integration
-
-> Load skills: command-center-builder, command-center-project, component-library, using-salesforce-data.
-> Refer to `docs/engine-command-center-prd.md` sections 11 and 13.
->
-> **Phase 3: Connect to Salesforce Data**
->
-> Replace sample data with live Salesforce data:
->
-> 1. **Create Data Hooks** - `src/hooks/`:
->    - `useFlights.ts` - Fetch active flights from Flight__c
->    - `useTravelers.ts` - Fetch travelers from Contact with flight relationships
->    - `useDisruptions.ts` - Fetch disruption cases from Case
->    - `useBookings.ts` - Fetch bookings from Booking__c
->    - `usePolicyItems.ts` - Fetch policy compliance from Policy__c
->    - `useEvaActions.ts` - Fetch Eva activity from Eva_Action__c
->    - `useSpendData.ts` - Fetch spend trends from aggregate query
->
-> 2. **GraphQL Queries** - For each hook, write GraphQL:
->    - Use @optional on all fields (FLS resilience)
->    - Include all relationships needed
->    - Add proper filters (Active__c = true, etc.)
->    - Use proper Salesforce field names from section 13
->
-> 3. **Replace Sample Data** - In EngineDashboard.tsx:
->    - Replace hardcoded arrays with hook calls
->    - Add loading states with CardSkeleton
->    - Add error states with EmptyState
->    - Add refresh functionality
->
-> 4. **Data Transformations** - Create `src/utils/engine-data-transforms.ts`:
->    - Transform Salesforce records to map data format
->    - Calculate KPI values from live data
->    - Aggregate data for charts
->    - Format dates, currencies, percentages
->
-> 5. **Real-time Updates** - Add DataModeToggle:
->    - Toggle between "sample" (Phase 2 data) and "live" (Salesforce data)
->    - Store preference in localStorage
->    - Show "Last synced" timestamp for live mode
->
-> 6. **Error Handling**:
->    - Network errors → Show retry button
->    - No data → Show EmptyState with action
->    - Partial data → Show what's available with warning
->
-> **DO NOT:**
-> - Add Agentforce/Eva chat yet
-> - Add complex AI features
-> - Modify component UI (should look same as Phase 2)
->
-> **Deliverable:** Dashboard connected to live Salesforce data with loading states, error handling, and ability to toggle between sample/live data for testing.
-
----
-
-### Prompt 4 — Agentforce Integration
-
-> Load skills: command-center-builder, command-center-project, component-library, managing-agentforce-conversation-client.
-> Refer to `docs/engine-command-center-prd.md` sections 9 and 10.
->
-> **Phase 4: Add Eva Agent**
->
-> Integrate Agentforce Eva agent:
->
-> 1. **Add ChatBar to Header**:
->    - Import ChatBar from @/components/library
->    - Position in header (right side, before theme toggle)
->    - Add keyboard shortcut (Cmd+K / Ctrl+K)
->    - Add starter suggestions:
->      - "Which travelers are affected by disruptions?"
->      - "Show me all delayed flights"
->      - "What's Eva doing right now?"
->      - "Summarize today's travel status"
->
-> 2. **Configure Eva Agent**:
->    - Use Agentforce Eva agent ID from PRD section 9
->    - Configure context: current user, visible data, dashboard state
->    - Add tool calls for dashboard actions:
->      - View traveler details
->      - Filter bookings
->      - Export data
->      - Refresh data
->
-> 3. **Add Salesforce Signals**:
->    - Header: "Powered by Salesforce Data Cloud" badge
->    - Traveler cards: "View in Salesforce" links → open Contact record
->    - Booking rows: "View in Salesforce" links → open Booking__c record
->    - Success toasts on actions: "Updated by Eva" with undo option
->    - Live sync indicator with timestamp
->
-> 4. **Eva Integration Points**:
->    - ChatBar can filter visible data
->    - ChatBar can expand specific travelers
->    - ChatBar can open specific bookings
->    - ChatBar can trigger refreshes
->    - ChatBar shows contextual suggestions based on current view
->
-> 5. **Testing Mode**:
->    - If no Eva agent configured, show mock responses
->    - Add "Configure Eva" EmptyState in ChatBar
->    - Link to Agentforce setup docs
->
-> **Deliverable:** Fully functional dashboard with Eva agent integrated, able to answer questions about travel data and perform dashboard actions.
-
----
+Each phase file is self-contained — it includes the code template, exact imports, and the 5 constraints that matter for that phase. No cross-references needed.
 
 ## Why This Works
 
-### Clear Phases
-Each phase has a single focus:
-1. Structure → Can review layout before building components
-2. Components → Can test UX/interactions before data complexity
-3. Data → Can focus on data fetching/transformation without UI changes
-4. Agent → Can add AI on top of working dashboard
-
-### Easy Testing
-- Phase 1: Review layout, spacing, branding
-- Phase 2: Test all interactions, edge cases with known data
-- Phase 3: Test loading states, errors, real data shapes
-- Phase 4: Test agent responses, tool calls
-
-### Easy Debugging
-- UI issues? → Phase 2
-- Data issues? → Phase 3
-- Agent issues? → Phase 4
-
-### Easy Iterations
-- Don't like layout? → Go back to Phase 1
-- Component not working? → Fix in Phase 2 with sample data
-- Data mapping wrong? → Fix Phase 3 transforms
-- Agent not helpful? → Improve Phase 4 prompts
-
-### Can Stop Early
-- Need just the UI mockup? → Stop after Phase 2
-- Don't have Salesforce yet? → Stop after Phase 2
-- Don't need AI? → Stop after Phase 3
-
----
-
-## Phase Checklist Template
-
-### Phase 1: Layout ✓
-- [ ] Header structure
-- [ ] Hero section containers
-- [ ] Data panel grid
-- [ ] Placeholder cards in place
-- [ ] Theme/branding applied
-- [ ] Proper spacing and responsive layout
-
-### Phase 2: Components ✓
-- [ ] Sample data file created
-- [ ] All components built
-- [ ] All interactions working
-- [ ] All visualizations working
-- [ ] Charts rendering with sample data
-- [ ] Table search/sort/pagination working
-- [ ] Dashboard looks and feels complete
-
-### Phase 3: Data ✓
-- [ ] All data hooks created
-- [ ] All GraphQL queries working
-- [ ] Loading states added
-- [ ] Error states handled
-- [ ] Data transformations working
-- [ ] Live/sample toggle working
-- [ ] Real data rendering correctly
-
-### Phase 4: Agent ✓
-- [ ] ChatBar in header
-- [ ] Eva agent configured
-- [ ] Starter suggestions working
-- [ ] Agent can answer questions
-- [ ] Tool calls working
-- [ ] Salesforce signals added
-- [ ] Links to Salesforce records working
-
----
-
-## Benefits Over Original Approach
-
-### Original Approach Issues:
-- Mixed layout + components + data in early prompts
-- Hard to debug what phase an issue is from
-- No clear stopping point
-- Can't test UI without data
-- Can't review structure before building
-
-### New Approach Benefits:
-- Clear separation of concerns
-- Each phase builds on previous
-- Easy to identify issue source
-- Can demo/test after each phase
-- Can iterate on each phase independently
-- Stakeholders can provide feedback earlier
+- Each phase has a single focus
+- Code templates mean less interpretation, faster builds
+- Self-contained files eliminate contradictions
+- Can stop after any phase (Phase 2 is a complete demo on its own)
 
----
+## Build Prompts
 
-## Notes
+Each phase is triggered by a simple prompt:
 
-- **Always use sample data mode in Phase 2** - DataModeProvider should default to "sample"
-- **Keep Phase 2 data file** - Useful for testing and demos
-- **Test Phase 3 with sample toggle** - Easy to compare live vs sample
-- **Phase 4 is optional** - Many dashboards don't need AI
-- **Can split Phase 2** - If many components, do 2a (map/KPIs) and 2b (panels/tables)
+- Phase 1: "Scaffold the Engine Travel Command Center skeleton"
+- Phase 2: "Replace placeholders with library components and sample data"
+- Phase 3: "Connect the dashboard to live Salesforce data"
+- Phase 4: "Add Eva ChatBar and Salesforce signals"

package/.a4drules/skills/command-center-builder/page-layout.md

@@ -108,9 +108,11 @@ Every dashboard needs a unique layout structure and at least one domain-specific
 
 ## Map Layout
 
-GeoMap should be placed in a **wide/narrow grid** (`lg:grid-cols-3` with `lg:col-span-2`), not full-width hero. Full-width maps dominate the page and waste space.
+**Default pattern:** GeoMap in a **wide/narrow grid** (`lg:grid-cols-3` with `lg:col-span-2`). This works well for dashboards where the map is one of several equal-weight sections.
 
-**Pattern: Map + sidebar at matched height**
+**If the PRD specifies a "visualization-hero" layout**, the map is full-width hero with glass overlays. The PRD always overrides this default pattern.
+
+**Default pattern: Map + sidebar at matched height**
 
 ```jsx
 <div className="grid grid-cols-1 gap-4 lg:grid-cols-3">