@schandlergarcia/sf-web-components 1.9.48 → 1.9.52

package/data/README.md

@@ -7,12 +7,11 @@ This directory contains pre-packaged data assets for demo builds and prototyping
 ```
 data/
 ├── engine-sample-data.js    # Engine Travel Command Center sample data
-└── README.md                # This file
+├── schema.graphql            # Pre-built GraphQL schema from sample data
+└── README.md                 # This file
 ```
 
-## Usage
-
-### Engine Travel Command Center Sample Data
+## Engine Travel Command Center Sample Data
 
 **Purpose:** Pre-seeded, dashboard-ready data for the Engine Travel demo. All field names match the Salesforce org schema (Trip__c, Flight__c, Booking__c, Disruption__c, Rebooking_Action__c, Travel_Policy__c) so switching from sample → live queries requires only a data-source swap.
 
@@ -45,20 +44,9 @@ Dashboard-ready derivatives (pre-computed for immediate use):
 - `SPEND_CHART_DATA` — Spend trend line data
 - `METRICS` — Computed KPI metrics (active travelers, spend MTD, compliance rate, etc.)
 
-**Copy to webapp:**
-
-When building the Engine dashboard, copy this file to your webapp source:
-
-```bash
-cp data/engine-sample-data.js force-app/main/default/webapplications/enginewebexperience/src/data/engine-sample-data.js
-```
-
-Or if you're starting fresh:
+**Installation:**
 
-```bash
-# From project root
-cp data/engine-sample-data.js <your-webapp-path>/src/data/
-```
+Automatically installed to `src/data/engine-sample-data.js` by postinstall script.
 
 **Import in components:**
 
@@ -105,6 +93,81 @@ All sample data uses Salesforce API field names:
 - Custom fields: `Trip__c`, `Flight_Number__c`, `Departure_Airport__c`, `Status__c`, etc.
 - Relationships: `Contact__c`, `Trip__c`, `Impacted_Flight__c`
 
+## GraphQL Schema
+
+**Purpose:** Pre-built GraphQL schema for Engine Travel Command Center. Works even when org introspection is broken.
+
+**Problem it solves:**
+
+Org introspection can fail with "cannot invoke FieldDataType.equals(Object) because the return value of Field.getDataType() is null". This breaks:
+- `npm run graphql:schema` (introspection query)
+- IDE autocomplete that queries org directly
+- GraphQL codegen from org schema
+
+But **queries still work** - introspection is just metadata.
+
+**Solution:**
+
+Pre-generate schema from sample data field names:
+1. Sample data already has correct Salesforce field names
+2. Generate `schema.graphql` from those field names
+3. Check schema into repo (automatically installed)
+4. GraphQL skills use the pre-built schema
+5. Queries execute normally using the same field names
+
+**Installation:**
+
+Automatically installed to `schema.graphql` (webapp root) by postinstall script.
+
+**Contents:**
+
+```graphql
+schema {
+  query: Query
+}
+
+type Query {
+  uiapi: UIAPI!
+}
+
+type UIAPI {
+  query: UIAPIQuery!
+}
+
+type UIAPIQuery {
+  Contact(first: Int, after: String, where: ContactFilter): ContactConnection
+  Trip__c(first: Int, after: String, where: Trip__cFilter): Trip__cConnection
+  Flight__c(first: Int, after: String, where: Flight__cFilter): Flight__cConnection
+  Booking__c(first: Int, after: String, where: Booking__cFilter): Booking__cConnection
+  Disruption__c(first: Int, after: String, where: Disruption__cFilter): Disruption__cConnection
+  Rebooking_Action__c(first: Int, after: String, where: Rebooking_Action__cFilter): Rebooking_Action__cConnection
+  Travel_Policy__c(first: Int, after: String, where: Travel_Policy__cFilter): Travel_Policy__cConnection
+}
+
+# ... Full schema with all types, connections, filters
+```
+
+**What this enables:**
+
+- ✅ `exploring-webapp-graphql-schema` skill works normally
+- ✅ `generating-webapp-graphql-read-query` skill works normally
+- ✅ `using-webapp-graphql` skill works normally
+- ✅ IDE autocomplete and validation
+- ✅ GraphQL codegen
+- ✅ Normal Phase 3 workflow without manual workarounds
+- ✅ Works in CI/CD without org access
+
+**Regenerating:**
+
+If you add new fields to sample data:
+
+```bash
+# From the webapp directory
+npm run graphql:schema:sample
+```
+
+This regenerates `schema.graphql` from the current sample data file. Then commit the updated schema to git.
+
 ## Adding New Data Assets
 
 When adding new sample data:

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

@@ -0,0 +1,436 @@
+# Engine Travel Command Center
+
+Product Requirements Document · TDX26 Demo Build
+
+**Required skills:** `command-center-builder`, `command-center-project`, `component-library`, `outer-app`
+
+---
+
+## 1. Product Overview
+
+The Engine Travel Command Center is a real-time operations dashboard for corporate travel managers who use Engine (engine.com). It gives a single-screen view of every active traveler, booking, flight, policy flag, and agent interaction — built on Salesforce Data Cloud.
+
+It is not Engine's consumer-facing booking app. It is a personalized command center for one travel manager at one company.
+
+**Demo context:** Built live at TDX26 using Agentforce Vibes. The arc is: PRD → scaffold → data → agent → intelligence. Each build prompt maps to one beat.
+
+---
+
+## 2. Users
+
+**Primary — Sarah Chen, Travel Manager at Acme Corp**
+Manages Acme's travel program: bookings, policy enforcement, exceptions, traveler monitoring. Before this dashboard she worked across Engine's booking interface, email, and Salesforce separately.
+
+**Secondary — Eva (Agentforce Agent)**
+Engine's Agentforce-powered AI agent. Handles traveler requests autonomously — booking changes, policy questions, itinerary lookups. Resolves ~30% of requests without human involvement. Surfaces in the dashboard via `ChatBar` (command palette).
+
+---
+
+## 3. Brand Tokens
+
+Update `src/styles/global.css` — replace the existing `--color-brand-*` palette inside the `@theme inline` block. Do not add new CSS variables or custom properties outside this block.
+
+```css
+/* Engine teal brand palette */
+--color-brand-50:  #ECFDF9;
+--color-brand-100: #D1FAF0;
+--color-brand-200: #A7F3E1;
+--color-brand-300: #6EE7C8;
+--color-brand-400: #34D3AB;
+--color-brand-500: #5BC8C8;
+--color-brand-600: #0D9488;
+--color-brand-700: #0F766E;
+--color-brand-800: #115E59;
+--color-brand-900: #134E4A;
+--color-brand-950: #042F2E;
+```
+
+Additionally, add a custom `--color-engine-savings` token for the green savings accent:
+
+```css
+--color-engine-savings: #16A34A;
+```
+
+All component styling uses `brand-*` Tailwind classes for primary UI and Tailwind built-in colors (green, amber, red) for status. No hardcoded hex values in components. No `bg-indigo-*` or raw color classes for brand elements.
+
+**Typography:** Inter (already configured as `--font-sans` in global.css). No changes needed.
+
+**Icons:** Heroicons 2 exclusively (`@heroicons/react`). No Lucide, Font Awesome, or other libraries inside command center pages.
+
+---
+
+## 4. Architecture
+
+**Dashboard file:** `src/pages/EngineDashboard.tsx` (single file, `.tsx` — TypeScript project, React components MUST use `.tsx`)
+
+**Wiring:** `CommandCenter.tsx` imports and renders `EngineDashboard` inside the existing provider stack (`heroui-scope` → `AppThemeProvider` → `DataModeProvider` → `Toast.Provider`). Never recreate these providers in the dashboard.
+
+**Imports:** All components from `@/components/library` barrel. Theme access from `@/components/library/theme/AppThemeProvider`.
+
+---
+
+## 5. Layout — Visualization-Hero Pattern
+
+This dashboard uses the **visualization-hero** layout. The live flight map is the signature element.
+
+### Structure (top to bottom)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ HEADER BAR (h-12, sticky)                                   │
+│  Engine logo + "Travel Command Center" | ChatBar | actions  │
+├─────────────────────────────────────────────────────────────┤
+│ HERO MAP (flex: 1.15 1 0, GeoMap, dark theme)               │
+│                                                             │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐          │
+│  │ KPI     │ │ KPI     │ │ KPI     │ │ KPI     │  ← glass │
+│  │ overlay │ │ overlay │ │ overlay │ │ overlay │  overlays │
+│  └─────────┘ └─────────┘ └─────────┘ └─────────┘          │
+│                                                             │
+│  ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐       ← flight  │
+│  │ BA286 │ │ NH109 │ │ LH431 │ │ SQ 37 │       status    │
+│  └───────┘ └───────┘ └───────┘ └───────┘       strip      │
+├─────────────────────────────────────────────────────────────┤
+│ DATA PANELS (flex: 1 1 0, px-4 py-5, space-y-6)            │
+│                                                             │
+│  ┌─── 1/3 ───────┐ ┌─── 2/3 ────────────────────┐         │
+│  │ Disruptions    │ │ Active Travelers            │         │
+│  │ (custom panel) │ │ (expandable cards, scroll)  │         │
+│  └────────────────┘ └────────────────────────────┘         │
+│                                                             │
+│  ┌─── 1/2 ───────┐ ┌─── 1/2 ────────────────────┐         │
+│  │ Eva Activity   │ │ Travelers by Destination    │         │
+│  │ (ActivityCard) │ │ (ChartCard + D3Chart bar)   │         │
+│  └────────────────┘ └────────────────────────────┘         │
+│                                                             │
+│  ┌─── full width ────────────────────────────────┐         │
+│  │ Upcoming Bookings (TableCard, searchable,      │         │
+│  │ sortable, paginated)                           │         │
+│  └────────────────────────────────────────────────┘         │
+│                                                             │
+│  ┌─── 1/2 ───────┐ ┌─── 1/2 ────────────────────┐         │
+│  │ Policy Status  │ │ Monthly Travel Spend        │         │
+│  │ (StatusCard)   │ │ (ChartCard + D3Chart line)  │         │
+│  └────────────────┘ └────────────────────────────┘         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Layout Rules
+
+- Hero map: `<div className="relative" style={{ flex: "1.15 1 0", minHeight: 0 }}>`
+- Data panels: `style={{ flex: "1 1 0" }}` with `px-4 py-5` and `space-y-6`
+- Disruptions + Travelers: `grid grid-cols-1 items-start gap-4 lg:grid-cols-3` (disruptions 1/3, travelers `lg:col-span-2`)
+- Eva + Chart: `grid grid-cols-1 items-start gap-4 lg:grid-cols-2`
+- Bookings table: full width
+- Policy + Spend: `grid grid-cols-1 items-start gap-4 lg:grid-cols-2`
+- All grids use `items-start` for different-height cards
+
+### Phase 1 Placeholder Rules
+
+For skeleton/placeholder cards (Phase 1 only):
+
+**Data panel placeholders** use `BaseCard` with centered text:
+
+```tsx
+// ✅ Correct data panel placeholder
+<BaseCard>
+  <div className="h-48 flex items-center justify-center text-slate-400">
+    Disruptions Panel
+  </div>
+</BaseCard>
+
+// ❌ Wrong - title causes text to run together
+<BaseCard title="Disruptions">
+  <div className="text-slate-400">No disruptions detected</div>
+</BaseCard>
+```
+
+**Hero map** (render actual GeoMap component in Phase 1):
+
+```tsx
+// ✅ Correct - render actual GeoMap component (empty, no data)
+import { GeoMap, useAppTheme } from "@/components/library";
+
+export default function EngineDashboard() {
+  const { mode } = useAppTheme();
+  
+  return (
+    <div className="relative" style={{ flex: "1.15 1 0", minHeight: 0 }}>
+      <GeoMap
+        width={960}
+        height={520}
+        theme={mode === "dark" ? "dark" : "light"}
+        className="h-full w-full"
+      />
+    </div>
+  );
+}
+```
+
+In Phase 1:
+- GeoMap renders with NO markers, arcs, or overlays props
+- Uses `useAppTheme()` to get dark/light mode for theme prop
+
+// ❌ Wrong - wrapped in BaseCard
+<div className="relative" style={{ flex: "1.15 1 0", minHeight: 0 }}>
+  <BaseCard>
+    <GeoMap ... />
+  </BaseCard>
+</div>
+
+// ❌ Wrong - text placeholder instead of GeoMap component
+<div className="relative" style={{ flex: "1.15 1 0", minHeight: 0 }}>
+  <div className="flex h-full items-center justify-center bg-slate-100 dark:bg-slate-900">
+    <span className="text-slate-400">Hero Map (GeoMap)</span>
+  </div>
+</div>
+```
+
+All data panel placeholders use: BaseCard, no title, centered text, `h-48`, `text-slate-400`.
+
+Hero map uses: actual GeoMap component (no markers/arcs/overlays in Phase 1), direct render, fills hero container.
+
+---
+
+## 6. Header
+
+Compact `h-12` sticky header with dark background (`bg-slate-900 dark:bg-slate-950`).
+
+| Position | Content |
+|----------|---------|
+| Left | Engine logo (small square icon with `GlobeAltIcon` in `bg-brand-600`) + "ENGINE" wordmark + separator + "Travel Command Center" |
+| Right | `ChatBar` (Eva) + notification bell (with pending count badge) + theme toggle (sun/moon) |
+
+The `ChatBar` replaces any FAB or sliding panel. It opens inline as a command palette overlay.
+
+---
+
+## 7. Hero Map
+
+**Component:** `GeoMap` (from `@/components/library`)
+
+```jsx
+<GeoMap
+  width={960}
+  height={520}
+  theme={mode === "dark" ? "dark" : "light"}
+  markers={markers}
+  arcs={arcs}
+  overlays={overlays}
+  zoomable
+  className="h-full w-full"
+/>
+```
+
+**Markers:** One per city (origin and destination). Each marker: `{ id, lon, lat, label, active: true }`.
+
+**Arcs:** One per active flight route. Each arc: `{ id, from: [lon, lat], to: [lon, lat], progress: 0–1 }`. Set `danger: true` on disrupted routes (delayed 60+ min or grounded). The `progress` value places an animated pulsing dot showing the flight's current position along the great circle arc.
+
+**Overlays:** Weather/disruption zones as pulsing circles. Each overlay: `{ id, center: [lon, lat], radius: number }`.
+
+**Glass KPI overlays:** Four pills floating `absolute left-3 top-3` on the map:
+- Active Travelers (count)
+- Spend MTD (formatted with `fmtK()`)
+- Compliance %
+- Eva Resolved (count + "resolved")
+
+Each pill: `bg-black/40 backdrop-blur-md border border-white/10 rounded-lg px-3 py-1.5` with white text and icon.
+
+**Flight status strip:** Floating `absolute bottom-3 left-3 right-3`, horizontal scroll. One pill per active flight showing flight number + status chip (On Time = green, Delayed = amber, Grounded/Boarding = contextual). Same glass styling as KPI overlays.
+
+---
+
+## 8. Data Panels
+
+### 8a. Disruptions Panel (1/3 width)
+
+Custom inline component inside a `BaseCard`. Shows only flights that are delayed 60+ min or grounded.
+
+Each disruption card:
+- Severity dot (rose for grounded, amber for delayed) + flight number + severity label + delay minutes
+- Route + affected traveler name
+- Reason text
+- Eva action line with `SparklesIcon` showing what Eva is doing about it
+
+### 8b. Active Travelers (2/3 width)
+
+`BaseCard` with `maxBodyHeight={420}` for internal scroll. Expandable traveler cards.
+
+Each traveler row:
+- `Avatar` (initials) + name + department + origin → destination
+- `UIChip` for policy status (success = compliant, warning = exception)
+- Click to expand: 4-col grid showing Flight, Hotel, Return date, Destination
+
+### 8c. Eva Activity (1/2 width)
+
+`ActivityCard` showing Eva's autonomous actions. Each action has:
+- Title (what Eva did)
+- Subtitle (details + savings/context)
+- Status: `"complete"` or `"working"`
+- Timestamp
+
+### 8d. Travelers by Destination (1/2 width)
+
+`ChartCard` wrapping a `D3Chart` with `D3ChartTemplates.groupedBarChart`.
+- X-axis: destination city names (categorical — use `scaleBand`, not `scaleLinear`)
+- Y-axis: traveler count
+- Height: 280px
+- `responsive={true}`
+
+### 8e. Upcoming Bookings (full width)
+
+`TableCard` with columns: Traveler, Type, Route, Dates, Cost, Status, Policy.
+- `sortable`, `searchable`, `paginated`, `pageSize={5}`
+- Status column: custom render with colored chips (Confirmed = green, Pending = amber)
+- Policy column: `UIChip` with semantic tones (success/danger/warning)
+
+### 8f. Policy Compliance (1/2 width)
+
+`StatusCard` with policy rule items. Each item: `{ title, description, status, timestamp }`.
+- Status uses canonical values: `"operational"`, `"degraded"`
+- `showTimestamp` and `showProgress` enabled
+
+### 8g. Monthly Travel Spend (1/2 width)
+
+`ChartCard` wrapping a `D3Chart` with `D3ChartTemplates.lineChart`.
+- X-axis: month labels (Oct–Mar)
+- Y-axis: dollar amounts
+- Height: 240px
+- `responsive={true}`
+
+---
+
+## 9. Eva — ChatBar
+
+Eva surfaces as a `ChatBar` in the header. Not a FAB. Not a sliding panel. Not a `ChatPanel` in the grid.
+
+```jsx
+<ChatBar
+  title="Eva"
+  placeholder="Ask about travelers, bookings, policy, spend…"
+  suggestions={suggestions}
+  onSend={handleChat}
+/>
+```
+
+**Starter suggestions (3–5):**
+- "Who's traveling internationally right now?"
+- "Show bookings pending approval"
+- "What has Eva resolved today?"
+- "Travelers returning this week"
+
+**Agent responses:** Return structured `components` arrays for data (MetricCard, DataTable, StatusCard) — never markdown tables in text content.
+
+**Handler:** Define `handleChat` and `CHAT_SUGGESTIONS` at module scope (outside the component body) so they can be shared if an "open in tab" feature is added later.
+
+---
+
+## 10. Salesforce Signals
+
+Subtle, contextual indicators — like "Sent from iPhone", not promotional banners.
+
+| Signal | Location | Implementation |
+|--------|----------|----------------|
+| "Powered by Salesforce Data Cloud" | Header subtitle, next to "Travel Command Center" | `UIText` size xs, muted |
+| "Powered by Salesforce Data Cloud" | Glass KPI overlay or header area | White/translucent text |
+| "☁ View in Salesforce" | Traveler expanded view, booking rows | Micro-link, muted text |
+| "✓ Salesforce updated" | After rebook/approve actions | `toast()` with success tone |
+| "Powered by Agentforce" | ChatBar title or subtitle area | Small badge/chip |
+| "Last synced · Data Cloud" | Footer or header timestamp | Ticking timestamp, muted |
+
+---
+
+## 11. Dark Mode
+
+Mandatory on every element. The dashboard must work in both light and dark mode with no visual bugs.
+
+- Use the standard dark mode pairs from the builder rules (bg-white/dark:bg-slate-900, etc.)
+- The GeoMap has built-in dark/light themes — pass `theme={mode === "dark" ? "dark" : "light"}`
+- Glass overlays use `bg-black/40 backdrop-blur-md` which works in both modes
+- Custom inline components (disruption cards, flight chips) must include `dark:` variants on every color class
+- Never use `text-black` or `text-white` directly — use the slate scale
+- Theme toggle button in the header (sun/moon icon)
+
+---
+
+## 12. Data Model
+
+**Traveler** — `id`, `name`, `department`, `destination`, `origin`, `hotel`, `flight`, `return`, `status`, `policyStatus` (compliant | exception)
+
+**Flight** — `id`, `flight` (number), `route`, `dep` (time), `status` (On Time | Delayed | Boarding | In Air | Landed), `traveler`, `delayMin`
+
+**Disruption** — `id`, `flight`, `route`, `traveler`, `severity` (grounded | delayed), `delayMin`, `reason`, `evaAction`
+
+**Map Coordinates** — City name → `[lon, lat]` lookup object. Markers derived from coordinates. Arcs derived from flight origin/destination pairs.
+
+**Booking** — `id`, `traveler`, `type`, `destination`, `dates`, `cost`, `status` (Confirmed | Pending approval), `policy` (In policy | Over budget | Exception granted)
+
+**Policy Item** — `id`, `title`, `description`, `status` (operational | degraded), `timestamp`
+
+**Eva Action** — `id`, `title`, `subtitle`, `status` (complete | working), `timestamp`
+
+**Monthly Spend** — `{ x: month, y: amount }` array
+
+**Destination Chart** — `{ x: city, travelers: count }` array
+
+**Sample data:** 8–10 travelers, 8 flights, 4 disruptions, 8 bookings, 5 policy items, 8 Eva actions, 6 months of spend. All deterministic (no `Math.random()`). Include realistic names, routes, dollar amounts, and a mix of all status types.
+
+---
+
+## 13. Build Prompts
+
+**Build Methodology:** 4-phase incremental process (Layout → Components → Data → Agent). Run prompts in sequence. All detailed instructions are in the skills and PRD — the phase prompts should be simple triggers.
+
+---
+
+### Phase 1: Layout & Structure
+
+> **Skills:** command-center-builder, command-center-project, component-library, outer-app
+>
+> Scaffold the Engine Travel Command Center skeleton. Build the structure from section 5 (visualization-hero layout) with placeholder cards. No real data or components yet, just the layout structure.
+
+---
+
+### Phase 2: Components & Sample Data
+
+> **Skills:** command-center-builder, command-center-project, component-library
+>
+> Replace placeholders with library components. Import data from the pre-existing `src/data/engine-sample-data.js` file. Build all panels from section 8.
+
+---
+
+### Phase 3: Real Data Integration
+
+> Use the Salesforce GraphQL skills to connect the dashboard to live data. Read `src/data/engine-sample-data.js` to see which fields are needed, then use the skills to implement queries and hooks for Contact, Trip__c, Flight__c, Booking__c, Disruption__c, and Rebooking_Action__c. Update EngineDashboard.tsx to use live data with `useDataSource({ sample: X, live: liveData })`. Add loading and error states. UI stays identical - live data only, no toggle needed.
+
+---
+
+### Phase 4: Agentforce Integration
+
+> **Skills:** command-center-builder, command-center-project, component-library
+>
+> Add Eva ChatBar to header. Add Salesforce signals throughout. Configure tool calls for filtering/highlighting. Fallback mode if Eva not configured.
+
+---
+
+## 14. What NOT to Do
+
+These are explicit anti-patterns. If any prompt output includes these, it must be corrected:
+
+- Do not use `react-simple-maps`, Recharts, or any charting library other than the built-in `D3Chart` + `D3ChartTemplates`
+- Do not use Lucide icons, Font Awesome, or any icon library other than Heroicons 2
+- Do not import from `src/components/ui/` (shadcn) — use `@/components/library` exclusively
+- Do not use `cn()` helper — that belongs to the outer app
+- Do not recreate `AppThemeProvider`, `DataModeProvider`, or `Toast.Provider` — `CommandCenter.tsx` provides them
+- Do not build a FAB or sliding chat panel — use `ChatBar` in the header
+- Do not hardcode hex color values in component JSX — use `brand-*` Tailwind classes and Tailwind built-in colors for status
+- Do not use `bg-indigo-*` for brand — use `brand-*`
+- Do not use `text-black` or `text-white` — use the slate scale
+- Do not put more than 4 KPIs in a row
+- Do not squeeze the map into a grid column — it must be full-width hero
+- Do not wrap GeoMap in ChartCard — render it directly
+- Do not use `Math.random()` in sample data
+- Do not skip dark mode on any visible element
+- Do not use inline `style={{}}` for layout except the flex properties on the hero/panel containers
+- Do not put `ChatPanel` in the dashboard grid
+- Do not use `position: fixed` without `createPortal` to `document.body`