@schandlergarcia/sf-web-components 1.9.59 → 1.9.60

package/.a4drules/features/engine-dashboard-rule.md

@@ -16,18 +16,29 @@ These rules apply ONLY when building the Engine Travel Command Center dashboard
 
 The Engine dashboard uses a **strict 4-phase build process.** You MUST complete each phase fully before starting the next:
 
-1. **Phase 1: Layout** — Structure only, placeholders, no real components
-2. **Phase 2: Components + Sample Data** — Full UI with hardcoded realistic data
+1. **Phase 1: Layout** — Complete layout structure (header, map, glass KPI overlays, flight strip) + data panel placeholders ONLY
+2. **Phase 2: Components + Sample Data** — Replace data panel placeholders with real library components + sample data
    - **CRITICAL:** Sample data file already exists at `src/data/engine-sample-data.js`
    - **DO NOT create a new data file** — just import from the existing one
-   - Import dashboard-ready derivatives (MAP_MARKERS, TRAVELER_CARDS, etc.)
+   - Import dashboard-ready derivatives (MAP_MARKERS, TRAVELER_CARDS, ESCALATION_CARDS, DESTINATION_CHART_DATA)
    - DO NOT define sample data inline in the dashboard — causes file truncation
+   - **FOLLOW THE EXACT CODE EXAMPLES in PRD Section 8c and 8d** - copy the code blocks as shown
+   - Panel titles: "Disruptions", "Active Travelers", "Escalations", "Travelers by Destination"
+   - Chart must use gradient color array, barRadius: 8, height: 320 (see PRD Section 8d code block)
+   - **DO NOT run validation or dev server** — phase is complete after wiring files
 3. **Phase 3: Real Data** — Connect to Salesforce, keep UI identical to Phase 2
 4. **Phase 4: Agent** — Add Eva ChatBar integration
 
-### Phase 1 Placeholder Format
+### Phase 1 Scope
 
-**Data panels** use `BaseCard` with centered placeholder text. NO titles on placeholders:
+**What to build in Phase 1:**
+- ✅ Header bar with logo, title, and theme toggle (use slate scale colors, NO text-white)
+- ✅ Hero map (GeoMap component with NO markers/arcs/overlays PROPS passed)
+- ✅ Glass KPI overlays (4 hardcoded values, positioned absolutely over map)
+- ✅ Flight status strip (4 hardcoded flights, positioned at map bottom)
+- ✅ Data panel placeholders (BaseCard with centered text) - **ONLY these are placeholders**
+
+**Data panel placeholders** use `BaseCard` with centered placeholder text. NO titles on placeholders:
 
 ```tsx
 <BaseCard>
@@ -40,13 +51,14 @@ The Engine dashboard uses a **strict 4-phase build process.** You MUST complete
 **Hero map** renders the actual GeoMap component (empty, no data):
 
 ```tsx
-import { GeoMap, useAppTheme } from "@/components/library";
+import { GeoMap } from "@/components/library";
+import { useThemeMode } from "@/components/library/theme/AppThemeProvider";
 
 export default function EngineDashboard() {
-  const { mode } = useAppTheme();
+  const { mode } = useThemeMode();
   
   return (
-    <div className="relative" style={{ flex: "1.15 1 0", minHeight: 0 }}>
+    <div className="relative h-[520px]">
       <GeoMap
         width={960}
         height={520}
@@ -60,13 +72,18 @@ export default function EngineDashboard() {
 
 All data panel placeholders: BaseCard, no title, centered text, `h-48`, `text-slate-400`.
 
-Hero map in Phase 1: actual GeoMap component (no markers/arcs/overlays yet), NOT wrapped in BaseCard.
+Hero map in Phase 1: actual GeoMap component with NO `markers`/`arcs`/`overlays` props passed (these are GeoMap data props for Phase 2+). The base world map (land, sphere, graticule) will render even with no data. Glass KPI overlays and flight status strip ARE built in Phase 1 as separate `<div>` elements positioned absolutely over the map - these provide visual confirmation the map area is rendering. GeoMap is NOT wrapped in BaseCard.
+
+**Verify the map renders:** After building, check that you can see the world map base layer (blue land on dark theme, gray land on light theme). If the map area appears blank, check:
+- Container has fixed height (`className="relative h-[520px]"`)
+- GeoMap has `className="h-full w-full"`
+- No console errors from GeoMap component
 
 **DO NOT:**
 - Mix phases (don't add sample data in Phase 1, don't add Eva in Phase 2, etc.)
-- Skip validation between phases
-- Proceed to the next phase with validator errors
+- Run `npm run dev` or `npm run validate:dashboard` (wastes turns, not required)
 - Use BaseCard titles in Phase 1 placeholders (causes text to run together)
+- Use `h-screen` or viewport-locked layout (full-page scroll required)
 
 ### Phase 3: Real Data Integration
 
@@ -138,29 +155,13 @@ The `useDataSource` hook automatically uses `live` data when available, falling
 
 **Troubleshooting:** If you encounter GraphQL schema introspection failures, see `.a4drules/troubleshooting/graphql-introspection-failure.md` for the complete workaround pattern.
 
-## Validation Checkpoints (ZERO ERRORS REQUIRED)
-
-After EVERY change, run the validator from the webapp directory:
-
-```bash
-cd force-app/main/default/webapplications/reactapp4
-npm run validate:dashboard
-```
+## Phase Completion (NO VALIDATION REQUIRED)
 
-**Zero errors required.** If the validator reports ANY errors:
-1. Read the error message carefully
-2. Identify which rule was violated
-3. Fix it by switching to the correct library component
-4. Re-run the validator
-5. Repeat until zero errors
+After wiring the dashboard into CommandCenter, Home, and routes, the phase is complete.
 
-**Common fixes:**
-- "Hand-rolled card detected" → Wrap in `WidgetCard`, `ListCard`, `BaseCard`, etc.
-- "Forbidden color: text-white" → Change to `text-slate-50` or `text-slate-900`
-- "shadcn import detected" → Replace with library equivalent from `@/components/library`
-- "Missing useDataSource" → Add `useDataSource({ sample, live })` pattern
+**🚫 CRITICAL: DO NOT run `npm run dev` or `npm run validate:dashboard`** 
 
-Do NOT report the phase as complete until the validator shows zero errors.
+These commands are NOT required for phase completion. Do NOT execute them. The phase is complete after wiring the files.
 
 ## File Requirements
 
@@ -168,15 +169,18 @@ Do NOT report the phase as complete until the validator shows zero errors.
 - **Location:** `src/pages/EngineDashboard.tsx` (NOT `src/components/pages/`)
 - **Imports:** ONLY from `@/components/library` — never shadcn, never Lucide, never Recharts
 
-## Layout Pattern: Visualization-Hero
+## Layout Pattern: Visualization-Hero with Full-Page Scroll
 
 The Engine dashboard uses the **visualization-hero** layout (see PRD section 5). This means:
 
-1. **Hero map:** Full-width, large (`flex: 1.15 1 0`), GeoMap with glass overlays and flight status strip
-2. **Data panels below:** Standard grid sections (`flex: 1 1 0`)
+1. **Hero map:** Full-width, fixed height (`h-[520px]`), GeoMap with glass overlays and flight status strip
+2. **Data panels below:** Natural flow with `px-4 py-5` (NO overflow constraints)
+3. **Full-page scroll:** Entire dashboard scrolls naturally (NO `h-screen` on outer container)
 
 **DO NOT:**
 - Put the map in a 1/3 or 1/2 grid column (it's hero, not sidebar)
+- Use `h-screen` or viewport-locked layout (full-page scroll required)
+- Use `overflow-y-auto` or flex height constraints on data panels
 - Wrap GeoMap in ChartCard (render directly)
 - Skip the glass KPI overlays or flight status strip
 - Make the map too small (minimum 400px height)
@@ -295,8 +299,9 @@ These elements distinguish the Engine dashboard from generic dashboards. They mu
 - Multi-tab layout with content swapping (build one scrollable page)
 - `<nav>` or header bar inside the dashboard (AppLayout handles navigation)
 - Map in a sidebar grid (it's hero — full width)
+- **Using `h-screen` or viewport-locked layout** (full-page scroll required)
 - More than 4 KPIs in a row
 - Using `Math.random()` in sample data
-- Skipping validator errors
+- **Running `npm run dev` or `npm run validate:dashboard`** (not required, wastes turns)
 - Reporting phase complete before wiring the dashboard into the app
 - Mixing phases (adding sample data in Phase 1, adding Eva in Phase 2, etc.)

package/.a4drules/features/pre-code-checklist.md

@@ -8,6 +8,18 @@ paths:
 
 Before writing any code for command center dashboards, verify these requirements from the PRD and skills.
 
+## FIRST: Read These Files
+
+**Before writing a single line of code, read these files:**
+1. `.a4drules/skills/component-library/SKILL.md` (lines 15-40) - Import Pattern section
+2. `engine-command-center-prd.md` - Phase 1 Placeholder Rules section
+3. This file - Phase 1 Code Template section
+
+**Verify you know:**
+- [ ] Exact import statement for `useThemeMode` hook
+- [ ] What "Phase 1 placeholder" means (data panels ONLY, not entire dashboard)
+- [ ] Which colors are forbidden (`text-white`, `text-black`, `bg-black` without opacity)
+
 ## File Creation Checklist
 
 When creating a new dashboard file, confirm:
@@ -15,7 +27,83 @@ When creating a new dashboard file, confirm:
 1. **File path:** `src/pages/DashboardName.tsx` (NOT `src/components/pages/`)
 2. **File extension:** `.tsx` (NOT `.jsx`) — this is a TypeScript project
 3. **Imports:** `@/components/library` ONLY (NOT `@/components/ui/`, NOT `lucide-react`, NOT `recharts`)
-4. **Colors:** Slate scale ONLY (NOT `text-white`, NOT `text-black`, NOT `bg-black`)
+4. **Import names:** Check SKILL.md for exact names — DO NOT guess or invent import names
+   - Theme toggle: `useThemeMode` (NOT `useAppTheme`, NOT `useTheme`)
+   - Data source: `import useDataSource from "..."` (default export, NOT named)
+5. **Colors:** Slate scale ONLY (NOT `text-white`, NOT `text-black`, NOT `bg-black`)
+
+## Phase 1 Code Template
+
+**START WITH THIS EXACT STRUCTURE:**
+
+```tsx
+import { GeoMap, BaseCard } from "@/components/library";
+import { useThemeMode } from "@/components/library/theme/AppThemeProvider";
+import { /* Heroicons */ } from "@heroicons/react/24/outline";
+
+export default function EngineDashboard() {
+  const { mode, toggle } = useThemeMode();
+
+  return (
+    <div className="flex flex-col bg-slate-50 dark:bg-slate-950">
+      {/* Header Bar - h-12, sticky, slate-900 bg */}
+      <header className="sticky top-0 z-50 flex h-12 items-center justify-between border-b border-slate-800 bg-slate-900 px-4">
+        {/* Logo + title with text-slate-50 (NOT text-white) */}
+      </header>
+
+      {/* Hero Map - fixed height h-[520px], GeoMap renders world automatically */}
+      <div className="relative h-[520px]">
+        <GeoMap width={960} height={520} theme={mode === "dark" ? "dark" : "light"} className="h-full w-full" />
+        
+        {/* Glass KPI overlays - positioned absolutely, text-slate-50 */}
+        <div className="absolute left-3 top-3 flex gap-2">
+          {/* 4 KPI divs with border-white/10, bg-black/40, backdrop-blur-md */}
+        </div>
+
+        {/* Flight status strip - positioned absolutely at bottom */}
+        <div className="absolute bottom-3 left-3 right-3 flex gap-2 overflow-x-auto">
+          {/* 4 flight divs with status badges */}
+        </div>
+      </div>
+
+      {/* Data Panels - natural flow, full-page scroll, 4 panels total */}
+      <div className="px-4 py-5">
+        <div className="space-y-6">
+          {/* Row 1: Disruptions (1/3) + Active Travelers (2/3) */}
+          <div className="grid grid-cols-1 items-start gap-4 lg:grid-cols-3">
+            <BaseCard>
+              <div className="flex h-48 items-center justify-center text-slate-400">
+                Disruptions Panel
+              </div>
+            </BaseCard>
+            <div className="lg:col-span-2">
+              <BaseCard>
+                <div className="flex h-48 items-center justify-center text-slate-400">
+                  Active Travelers Panel
+                </div>
+              </BaseCard>
+            </div>
+          </div>
+
+          {/* Row 2: Escalations (1/2) + Destination Chart (1/2) */}
+          <div className="grid grid-cols-1 items-start gap-4 lg:grid-cols-2">
+            <BaseCard>
+              <div className="flex h-48 items-center justify-center text-slate-400">
+                Escalations Panel
+              </div>
+            </BaseCard>
+            <BaseCard>
+              <div className="flex h-48 items-center justify-center text-slate-400">
+                Travelers by Destination Panel
+              </div>
+            </BaseCard>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
 
 ## During Code Generation Checklist
 
@@ -25,9 +113,19 @@ As you write the dashboard code:
 2. **Every chart** uses `ChartCard` + `D3Chart` or `GeoMap` — NO Recharts, NO Chart.js, NO custom SVG
 3. **Every color** uses semantic classes or slate scale — NO `text-white`, NO `bg-black`, NO hardcoded hex
 4. **Dark mode** on every element — `dark:` variants on all custom styling
-5. **Phase 1 placeholders:**
-   - Data panels: use BaseCard with NO title prop, centered text
-   - Hero map: render actual GeoMap component (empty, no markers/arcs/overlays), NOT wrapped in BaseCard
+5. **Phase 1 scope - Build COMPLETE layout structure:**
+   - ✅ Outer container: `className="flex flex-col bg-slate-50 dark:bg-slate-950"` (NO `h-screen` - full-page scroll)
+   - ✅ Header bar (logo, title, actions) with slate scale colors (NO text-white)
+   - ✅ Header text: ONLY "ENGINE" + "Travel Command Center" (NO "Powered by..." branding in Phase 1)
+   - ✅ Hero map container: `className="relative h-[520px]"` (fixed height, NOT flex-based)
+   - ✅ Hero map (GeoMap component with NO markers/arcs/overlays PROPS, `className="h-full w-full"`)
+   - ✅ Glass KPI overlays (4 hardcoded KPIs, positioned absolutely over map)
+   - ✅ Flight status strip (4 hardcoded flights, positioned at map bottom)
+   - ✅ Data panels container: `className="px-4 py-5"` (NO `overflow-y-auto`, NO flex constraints - natural flow)
+   - ✅ **4 data panel placeholders** (2 rows: Disruptions/Travelers, Escalations/Destinations) - BaseCard with NO title prop, centered text
+   - ❌ **Phase 1 EXCLUDES:** Salesforce/Data Cloud branding (Phase 4), ChatBar (Phase 4), real data (Phase 2+)
+   - "Placeholder" means data panels below the map, NOT the header/overlays/map
+   - **Full-page scroll:** Entire dashboard scrolls naturally (map scrolls up as user scrolls down)
 
 ## After Code Generation Checklist
 
@@ -38,13 +136,33 @@ After writing the dashboard code:
    - [ ] `Home.tsx` renders `CommandCenter`
    - [ ] `routes.tsx` has correct routes
 
-2. **Validation:**
-   ```bash
-   cd force-app/main/default/webapplications/reactapp4
-   npm run validate:dashboard
-   ```
-   - [ ] Zero errors required
-   - [ ] Fix all errors before proceeding
+2. **Completion:**
+   - [ ] All files wired correctly
+   - [ ] **DO NOT run `npm run dev` or `npm run validate:dashboard`** - not required for ANY phase completion
+
+## Color Reference (CRITICAL)
+
+**NEVER use these:**
+
+| ❌ FORBIDDEN | ✅ USE INSTEAD | Where |
+|-------------|---------------|-------|
+| `text-white` | `text-slate-50` | Header text, overlay text |
+| `text-black` | `text-slate-900` | Body text (light mode) |
+| `bg-black` | `bg-slate-900` or `bg-black/40` (with opacity) | Backgrounds |
+| `bg-white` | `bg-slate-50` | Page background (light mode) |
+
+**Exception:** `bg-black/40`, `bg-white/10`, `border-white/10` are allowed (opacity variants for glass effect)
+
+## Verification Checklist
+
+After building, you should see:
+- [ ] Header bar with Engine logo and "Travel Command Center" title
+- [ ] **World map visible** (blue/teal land on dark background OR gray land on light background)
+- [ ] 4 glass KPI boxes in top-left of map (semi-transparent with numbers)
+- [ ] 4 flight status boxes at bottom of map (with colored badges)
+- [ ] **4 white/dark cards below map** (2 rows: row 1 has 1/3 + 2/3 split, row 2 has 1/2 + 1/2 split)
+- [ ] Page scrolls when you scroll the data panels section
+- [ ] Theme toggle works (sun/moon icon in header)
 
 ## Quick Reference
 
@@ -53,10 +171,11 @@ After writing the dashboard code:
 | File path? | `src/pages/EngineDashboard.tsx` |
 | Extension? | `.tsx` (TypeScript) |
 | Import from? | `@/components/library` |
-| Colors? | Slate scale (`text-slate-50`, `bg-slate-900`) |
+| Hook import? | `import { useThemeMode } from "@/components/library/theme/AppThemeProvider"` |
+| Colors? | Slate scale (`text-slate-50`, `bg-slate-900`) - NEVER `text-white` |
 | Cards? | Library components (MetricCard, ListCard, etc.) |
 | Charts? | `ChartCard` + `D3Chart` or `GeoMap` |
-| Validate? | `npm run validate:dashboard` → zero errors |
+| After building? | Wire into CommandCenter/Home/routes - DO NOT run dev server |
 
 ## Common Mistakes to Avoid
 
@@ -66,6 +185,30 @@ After writing the dashboard code:
 ❌ `bg-black` → ✅ `bg-slate-900`
 ❌ `<div className="bg-white border rounded-lg p-4">` → ✅ `<BaseCard>` or `<WidgetCard>`
 ❌ `import { Button } from '@/components/ui/button'` → ✅ `import { UIButton } from '@/components/library'`
+❌ `import { useAppTheme } from '@/components/library'` → ✅ `import { useThemeMode } from '@/components/library'`
+❌ `"Powered by Salesforce Data Cloud"` in Phase 1 → ✅ This is Phase 4 only (see PRD Section 10)
+❌ Running `npm run dev` after building → ✅ Not needed - validation is sufficient
+
+## Troubleshooting
+
+**If you get TypeScript error about imports:**
+1. ❌ DO NOT follow "did you mean default import?" suggestion
+2. ✅ READ `.a4drules/skills/component-library/SKILL.md` Import Pattern section
+3. ✅ USE the exact import shown in the docs
+
+**If map doesn't render:**
+1. ✅ Verify container has `style={{ flex: "1.15 1 0", minHeight: 0 }}`
+2. ✅ Verify GeoMap has `className="h-full w-full"`
+3. ✅ GeoMap shows world map automatically - no props needed
+
+**If colors look wrong:**
+1. ✅ Search your code for `text-white` - should be `text-slate-50`
+2. ✅ Search your code for `text-black` - should be `text-slate-900`
+3. ✅ Exception: `bg-black/40` and `border-white/10` (with opacity) are OK
+
+**If data panels don't scroll:**
+1. ✅ Verify data panels container has `overflow-y-auto` className
+2. ✅ Verify it has `style={{ flex: "1 1 0" }}`
 
 ## Enforcement
 

package/.a4drules/skills/component-library/SKILL.md

@@ -14,18 +14,55 @@ Vendored from command-center-starter. Do not modify library files.
 
 ## Import Pattern
 
+**CRITICAL: Do NOT guess or invent import names.** Check this file for exact names before writing imports.
+
 ```tsx
 // Named imports from the barrel (preferred)
 import { MetricCard, ChartCard, TableCard, ListCard } from "@/components/library";
 
 // Default exports that need direct import
-import useDataSource from "@/components/library/data/useDataSource";
-import { useThemeMode } from "@/components/library/theme/AppThemeProvider";
+import useDataSource from "@/components/library/data/useDataSource";  // DEFAULT export
+import { useThemeMode } from "@/components/library/theme/AppThemeProvider";  // NAMED export
 
 // Import types (TypeScript)
 import type { MetricCardProps } from "@/components/library";
 ```
 
+**Common name mistakes:**
+- ❌ `useAppTheme` → ✅ `useThemeMode`
+- ❌ `useTheme` → ✅ `useThemeMode`
+- ❌ `import { useDataSource }` → ✅ `import useDataSource` (no braces, default export)
+
+---
+
+## Do Not
+
+- **Guess or invent import names** — always check this file first. Common mistakes: `useAppTheme` (doesn't exist), `useTheme` (doesn't exist) → use `useThemeMode`
+- Use `import { useAppTheme }` or `import useThemeMode` (default) — **both are wrong**. The hook is `useThemeMode` (named export), the component is `AppThemeProvider` (default export). Correct: `import { useThemeMode } from "@/components/library/theme/AppThemeProvider"`. If TypeScript suggests "did you mean default import?" when you have the wrong name, check the docs — don't blindly switch to default import
+- `import { useDataSource }` — it's a **default** export, use `import useDataSource from "..."`
+- Import from individual library files when the barrel exports it
+- Modify vendored library files
+- Import shadcn (`@/components/ui/`) in command center code — shadcn components (`Button`, `Card`, `Input`, `Select`, `Alert`, `Skeleton`, etc.) exist for the outer app only. In command center pages, use the equivalent library component (`UIButton`, `BaseCard`/`WidgetCard`, `UIInput`, `Select`, `Alert`, `Skeleton`, etc. from `@/components/library`)
+- Use Lucide icons (`lucide-react`) in command center code — use Heroicons (`@heroicons/react`) instead
+- Pass `items` to ActivityCard — use `actions`
+- Pass children to CalloutCard — use `message` prop
+- Pass `(row)` to TableCard render — it receives `(value, row)`
+- Use `template` prop on D3Chart — use `renderChart` function reference
+- Wrap GeoMap in ChartCard — render directly in a container div
+- Use ActivityCard for scrollable feeds — use ListCard with `maxBodyHeight`
+- Use raw `Modal` for form dialogs — use `FormModal` instead
+- Use `Tabs` as page-level navigation — only use inside cards for sub-sections
+- Pass `filteredData` to components — use `sortedData` from usePageFilters
+- Use `CardSkeleton` and `Skeleton` interchangeably — `CardSkeleton` for card placeholders, `Skeleton` for inline shapes
+- Recreate form state manually — use `useFormState` hook
+- Use `ChatPanel` on dashboards — use `ChatBar` (command palette style)
+- Pass children to `WidgetCard` — it ignores children and shows "No sections." Use the `sections` prop instead: `<WidgetCard sections={[{ id: "main", content: <div>...</div> }]} />`
+- Add `p-5`, `p-6`, etc. to WidgetCard `header` or section `content` — BaseCard already applies `p-4` padding, so extra padding causes double spacing
+- Pass initials strings as `avatar` in ListCard items — `avatar: "MR"` is treated as an image URL and breaks. Instead, omit `avatar` to auto-generate initials from `title`/`name`, or pass a ReactNode like `<Avatar initials="MR" />`
+- Hand-roll a card container (`<div className="bg-white border rounded ...">`) when `WidgetCard` with a single section can wrap your custom content
+- Use Recharts, Chart.js, or any third-party chart library — only `D3Chart` and `GeoMap` are allowed
+- Dismiss `validate:dashboard` errors as "justified" — every error has a library component fix
+
 ---
 
 ## When to Use Each Component
@@ -998,31 +1035,3 @@ import { ScrollShadow } from "@/components/library";
 </ScrollShadow>
 ```
 Adds fade shadows at scroll edges to indicate more content.
-
----
-
-## Do Not
-
-- Import from individual library files when the barrel exports it
-- Modify vendored library files
-- Import shadcn (`@/components/ui/`) in command center code — shadcn components (`Button`, `Card`, `Input`, `Select`, `Alert`, `Skeleton`, etc.) exist for the outer app only. In command center pages, use the equivalent library component (`UIButton`, `BaseCard`/`WidgetCard`, `UIInput`, `Select`, `Alert`, `Skeleton`, etc. from `@/components/library`)
-- Use Lucide icons (`lucide-react`) in command center code — use Heroicons (`@heroicons/react`) instead
-- `import { useDataSource }` — it's a **default** export
-- Pass `items` to ActivityCard — use `actions`
-- Pass children to CalloutCard — use `message` prop
-- Pass `(row)` to TableCard render — it receives `(value, row)`
-- Use `template` prop on D3Chart — use `renderChart` function reference
-- Wrap GeoMap in ChartCard — render directly in a container div
-- Use ActivityCard for scrollable feeds — use ListCard with `maxBodyHeight`
-- Use raw `Modal` for form dialogs — use `FormModal` instead
-- Use `Tabs` as page-level navigation — only use inside cards for sub-sections
-- Pass `filteredData` to components — use `sortedData` from usePageFilters
-- Use `CardSkeleton` and `Skeleton` interchangeably — `CardSkeleton` for card placeholders, `Skeleton` for inline shapes
-- Recreate form state manually — use `useFormState` hook
-- Use `ChatPanel` on dashboards — use `ChatBar` (command palette style)
-- Pass children to `WidgetCard` — it ignores children and shows "No sections." Use the `sections` prop instead: `<WidgetCard sections={[{ id: "main", content: <div>...</div> }]} />`
-- Add `p-5`, `p-6`, etc. to WidgetCard `header` or section `content` — BaseCard already applies `p-4` padding, so extra padding causes double spacing
-- Pass initials strings as `avatar` in ListCard items — `avatar: "MR"` is treated as an image URL and breaks. Instead, omit `avatar` to auto-generate initials from `title`/`name`, or pass a ReactNode like `<Avatar initials="MR" />`
-- Hand-roll a card container (`<div className="bg-white border rounded ...">`) when `WidgetCard` with a single section can wrap your custom content
-- Use Recharts, Chart.js, or any third-party chart library — only `D3Chart` and `GeoMap` are allowed
-- Dismiss `validate:dashboard` errors as "justified" — every error has a library component fix

package/.a4drules/webapp-data.md

@@ -251,10 +251,9 @@ if (response?.errors?.length) {
 }
 
 const accounts = response?.data?.uiapi?.query?.Account?.edges?.map(e => e.node) ?? [];
+```
 
----
-
-## Sample Data Cache Pattern
+### Sample Data Cache Pattern
 
 The app uses `useDataSource` to provide a sample data cache for optimal performance:
 
@@ -279,63 +278,6 @@ const travelers = useDataSource({
 3. The cache provides instant loading and offline capability
 4. All code is production-ready — switching to live data requires only changing the flag
 
-**Example implementation:**
-
-```typescript
-// 1. Create the data hook with real GraphQL query
-function useTravelers() {
-  const [data, setData] = useState<any[] | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  useEffect(() => {
-    async function fetchData() {
-      try {
-        const sdk = await createDataSDK();
-        const response = await sdk.graphql?.(GET_TRAVELERS);
-        
-        if (response?.errors?.length) {
-          throw new Error(response.errors.map((e: any) => e.message).join("; "));
-        }
-        
-        const travelers = response?.data?.uiapi?.query?.Contact?.edges?.map((e: any) => e.node) ?? [];
-        setData(travelers);
-      } catch (err) {
-        setError(err instanceof Error ? err : new Error(String(err)));
-      } finally {
-        setLoading(false);
-      }
-    }
-    fetchData();
-  }, []);
-
-  return { data, loading, error };
-}
-
-// 2. Use in component with useDataSource pattern
-function TravelersPanel() {
-  const { data: liveTravelers } = useTravelers();
-  const travelers = useDataSource({
-    sample: SAMPLE_TRAVELERS,
-    live: liveTravelers ?? [],
-  });
-
-  return <TravelersList travelers={travelers} />;
-}
-```
-
-**Benefits:**
-- ✓ Instant data loading (no network latency)
-- ✓ No API rate limiting concerns
-- ✓ Consistent data for demos and testing
-- ✓ Works offline
-- ✓ Reduced backend load
-
-**DO NOT:**
-- Disable the cache or mention it as a "demo mode" limitation
-- Skip building real GraphQL queries — always build them
-- Add toggle UI for switching between sample/live — the flag handles it
-
 ---
 
 ## REST API Patterns

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.60] - 2026-04-01
+
+### Updated
+- **Synced .a4drules and PRD from reactapp4** - Updated all documentation and rules
+  - `.a4drules/features/engine-dashboard-rule.md` - Updated Phase 1/Phase 2 guidance with exact code examples
+    - Added specific instructions to follow PRD Section 8c/8d code blocks exactly
+    - Clarified Phase 1 includes glass KPI overlays and flight status strip (not just placeholders)
+    - Added chart configuration details (gradient colors, barRadius: 8, height: 320)
+    - Fixed import example to use `useThemeMode` (not `useAppTheme`)
+  - `.a4drules/features/command-center-dashboard-rule.md` - Latest dashboard rules
+  - `.a4drules/features/phase2-data-pattern.md` - Sample data wiring patterns
+  - `.a4drules/features/pre-code-checklist.md` - Pre-implementation checklist
+  - `.a4drules/skills/` - All skills updated from reactapp4
+  - `.a4drules/troubleshooting/` - Troubleshooting guides
+  - `.a4drules/validation-requirements.md` - Latest validation rules
+  - `.a4drules/webapp-data.md` - Data access patterns
+  - `.a4drules/webapp-ui.md` - UI platform rules
+  - `data/engine-command-center-prd.md` - Latest PRD with updated build instructions
+
+### Context
+The reactapp4 project had the most up-to-date Engine Travel Command Center documentation including the corrected `useThemeMode` hook import pattern and detailed phase-by-phase build instructions. This sync ensures all new projects get the latest guidance.
+
 ## [1.9.59] - 2026-04-01
 
 ### Fixed

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

@@ -80,54 +80,56 @@ This dashboard uses the **visualization-hero** layout. The live flight map is th
 │ 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)  │         │
-│  └────────────────┘ └────────────────────────────┘         │
+│ HERO MAP (h-[520px] or h-[600px], GeoMap)                  │  ↕
+│                                                             │  ↕ Full-page
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐          │  ↕ scroll
+│  │ KPI     │ │ KPI     │ │ KPI     │ │ KPI     │  ← glass │  ↕
+│  │ overlay │ │ overlay │ │ overlay │ │ overlay │  overlays │  ↕
+│  └─────────┘ └─────────┘ └─────────┘ └─────────┘          │  ↕
+│                                                             │  ↕
+│  ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐       ← flight  │  ↕
+│  │ BA286 │ │ NH109 │ │ LH431 │ │ SQ 37 │       status    │  ↕
+│  └───────┘ └───────┘ └───────┘ └───────┘       strip      │  ↕
+├─────────────────────────────────────────────────────────────┤  ↕
+│ DATA PANELS (px-4 py-5, space-y-6, natural flow)           │  ↕
+│                                                             │  ↕
+│  ┌─── 1/3 ───────┐ ┌─── 2/3 ────────────────────┐         │  ↕
+│  │ Disruptions    │ │ Active Travelers            │         │  ↕
+│  │ (custom panel) │ │ (expandable cards, scroll)  │         │  ↕
+│  └────────────────┘ └────────────────────────────┘         │  ↕
+│                                                             │  ↕
+│  ┌─── 1/2 ───────┐ ┌─── 1/2 ────────────────────┐         │  ↕
+│  │ Escalations    │ │ Travelers by Destination    │         │  ↕
+│  │ (ActivityCard) │ │ (ChartCard + D3Chart)       │         │  ↕
+│  └────────────────┘ └────────────────────────────┘         │  ↕
 └─────────────────────────────────────────────────────────────┘
 ```
 
 ### 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`
+**CRITICAL: Full-page scroll, NOT viewport-locked sections.**
+
+The entire dashboard scrolls as one page. Do NOT use `h-screen` or flex height constraints that lock sections to viewport.
+
+- **Outer container:** `<div className="flex flex-col bg-slate-50 dark:bg-slate-950">` (NO `h-screen`)
+- **Hero map:** Fixed height `h-[520px]` or `h-[600px]` with `relative` positioning for glass overlays
+- **Data panels:** Natural flow with `px-4 py-5 space-y-6` (NO `overflow-y-auto`, NO flex height constraints)
+- **Row 1** - Disruptions + Travelers: `grid grid-cols-1 items-start gap-4 lg:grid-cols-3` (disruptions 1/3, travelers `lg:col-span-2`)
+- **Row 2** - Escalations + Chart: `grid grid-cols-1 items-start gap-4 lg:grid-cols-2`
 - All grids use `items-start` for different-height cards
 
+**Why full-page scroll:** Users need to see the map in context while scrolling through data. A fixed-height map that stays visible while data scrolls below creates a cramped, split-screen feeling. Full-page scroll is more natural and gives each section breathing room.
+
 ### Phase 1 Placeholder Rules
 
-For skeleton/placeholder cards (Phase 1 only):
+**Phase 1 builds the complete layout structure** including header bar, hero map, glass KPI overlays, flight status strip, and data panels. The only "placeholders" are the **data panels** below the map.
+
+**What to build in Phase 1:**
+- ✅ Header bar (with logo, title, theme toggle) - **use slate scale colors, NOT text-white**
+- ✅ Hero map (GeoMap component with no markers/arcs/overlays props)
+- ✅ Glass KPI overlays (4 KPIs, hardcoded values, positioned absolutely over map)
+- ✅ Flight status strip (4 flights, hardcoded values, positioned at map bottom)
+- ✅ Data panels (BaseCard placeholders with centered text) - **these are the only placeholders**
 
 **Data panel placeholders** use `BaseCard` with centered text:
 
@@ -149,13 +151,14 @@ For skeleton/placeholder cards (Phase 1 only):
 
 ```tsx
 // ✅ Correct - render actual GeoMap component (empty, no data)
-import { GeoMap, useAppTheme } from "@/components/library";
+import { GeoMap } from "@/components/library";
+import { useThemeMode } from "@/components/library/theme/AppThemeProvider";
 
 export default function EngineDashboard() {
-  const { mode } = useAppTheme();
+  const { mode } = useThemeMode();
   
   return (
-    <div className="relative" style={{ flex: "1.15 1 0", minHeight: 0 }}>
+    <div className="relative h-[520px]">
       <GeoMap
         width={960}
         height={520}
@@ -168,18 +171,21 @@ export default function EngineDashboard() {
 ```
 
 In Phase 1:
-- GeoMap renders with NO markers, arcs, or overlays props
-- Uses `useAppTheme()` to get dark/light mode for theme prop
+- GeoMap component renders with NO `markers`, `arcs`, or `overlays` props (these are GeoMap data props for Phase 2+)
+- GeoMap will render the base world map (land, sphere, graticule) even without data - this is NOT a placeholder, it's the actual map component
+- Glass KPI overlays and flight status strip ARE built in Phase 1 (as separate `<div>` elements positioned absolutely over the map)
+- Uses `useThemeMode()` to get dark/light mode for theme prop
+- **Verify:** You should see a blue world map (dark theme) or gray world map (light theme) with glass overlays on top
 
 // ❌ Wrong - wrapped in BaseCard
-<div className="relative" style={{ flex: "1.15 1 0", minHeight: 0 }}>
+<div className="relative h-[520px]">
   <BaseCard>
     <GeoMap ... />
   </BaseCard>
 </div>
 
 // ❌ Wrong - text placeholder instead of GeoMap component
-<div className="relative" style={{ flex: "1.15 1 0", minHeight: 0 }}>
+<div className="relative h-[520px]">
   <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>
@@ -242,6 +248,10 @@ Each pill: `bg-black/40 backdrop-blur-md border border-white/10 rounded-lg px-3
 
 ## 8. Data Panels
 
+**CRITICAL: Panel titles MUST match PRD exactly, even if data export has different name.**
+
+For example: Panel titled "Escalations" uses data exported as `EVA_ACTIONS` or `ESCALATION_CARDS` (both are aliases). The PRD panel title takes precedence over data export names.
+
 ### 8a. Disruptions Panel (1/3 width)
 
 Custom inline component inside a `BaseCard`. Shows only flights that are delayed 60+ min or grounded.
@@ -261,42 +271,70 @@ Each traveler row:
 - `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)
+### 8c. Escalations (1/2 width)
+
+`ActivityCard` showing escalations that require attention or can be sent to Eva for resolution.
+
+**Data source:** Import `ESCALATION_CARDS` from sample data (alias of `EVA_ACTIONS`)
+
+```tsx
+<ActivityCard
+  title="Escalations"
+  actions={useDataSource({ sample: ESCALATION_CARDS, live: [] })}
+/>
+```
 
-`ActivityCard` showing Eva's autonomous actions. Each action has:
-- Title (what Eva did)
-- Subtitle (details + savings/context)
-- Status: `"complete"` or `"working"`
+Each escalation has:
+- Title (issue description)
+- Subtitle (details + context)
+- Status: `"working"` (Eva is handling), `"pending"` (needs review), or `"complete"` (resolved)
 - Timestamp
 
+Examples from sample data:
+- "Processing approval for Omar Hassan" - subtitle: "Paris trip over budget · escalated to manager" (status: pending)
+- "Monitoring weather delay for Elena Rodriguez" - subtitle: "AF 99 · CDG arrival delayed 45 min · No action yet" (status: working)
+- "Rebooked cancelled flight for Sarah Chen" - subtitle: "LH 431 → LH 433 · Same fare class" (status: complete)
+
 ### 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)
+**CRITICAL: Use this exact code structure:**
 
-### 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
+```tsx
+<ChartCard
+  title="Travelers by Destination"
+  subtitle="Active trips by city"
+  chart={
+    <D3Chart
+      data={destinationData}
+      renderChart={D3ChartTemplates.groupedBarChart}
+      options={{
+        xKey: "x",
+        groups: ["travelers"],
+        colors: ["#5BC8C8", "#34D3AB", "#0D9488", "#0F766E", "#16A34A", "#5BC8C8", "#34D3AB", "#0D9488"],
+        barRadius: 8,
+        barPadding: 0.3,
+        margin: { top: 20, right: 20, bottom: 40, left: 40 },
+        showGrid: true,
+      }}
+      responsive
+      height={320}
+    />
+  }
+/>
+```
 
-### 8g. Monthly Travel Spend (1/2 width)
+**Requirements:**
+- X-axis: destination city names (categorical — `scaleBand` via xKey: "x")
+- Y-axis: traveler count (from groups: ["travelers"])
+- Height: 320px (NOT 280px)
+- Colors: **Must use gradient array** (8 colors, teal/green gradient matching Engine brand)
+- barRadius: 8 (NOT 4)
+- barPadding: 0.3 (for better spacing)
+- responsive={true}
 
-`ChartCard` wrapping a `D3Chart` with `D3ChartTemplates.lineChart`.
-- X-axis: month labels (Oct–Mar)
-- Y-axis: dollar amounts
-- Height: 240px
-- `responsive={true}`
+**That's it!** Only 4 panels total: Disruptions, Active Travelers, Escalations, and Travelers by Destination.
 
 ---
 
@@ -325,18 +363,17 @@ Eva surfaces as a `ChatBar` in the header. Not a FAB. Not a sliding panel. Not a
 
 ---
 
-## 10. Salesforce Signals
+## 10. Salesforce Signals (Phase 4 Only)
+
+**⚠️ These are added in Phase 4, NOT Phase 1.** Phase 1 has only the Engine logo and "Travel Command Center" title.
 
 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 |
+| Signal | Location | Implementation | Phase |
+|--------|----------|----------------|-------|
+| "☁ View in Salesforce" | Traveler expanded view, booking rows | Micro-link, muted text | Phase 4 |
+| "✓ Salesforce updated" | After rebook/approve actions | `toast()` with success tone | Phase 4 |
+| "Powered by Agentforce" | ChatBar title or subtitle area | Small badge/chip | Phase 4 |
 
 ---
 
@@ -367,13 +404,13 @@ Mandatory on every element. The dashboard must work in both light and dark mode
 
 **Policy Item** — `id`, `title`, `description`, `status` (operational | degraded), `timestamp`
 
-**Eva Action** — `id`, `title`, `subtitle`, `status` (complete | working), `timestamp`
+**Escalation** — `id`, `title`, `subtitle`, `status` (complete | working | pending), `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.
+**Sample data:** 8–10 travelers, 8 flights, 4 disruptions, 8 bookings, 5 policy items, 8 escalations, 6 months of spend. All deterministic (no `Math.random()`). Include realistic names, routes, dollar amounts, and a mix of all status types.
 
 ---
 
@@ -395,7 +432,7 @@ Mandatory on every element. The dashboard must work in both light and dark mode
 
 > **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.
+> Replace placeholders with library components. Import data from the pre-existing `src/data/engine-sample-data.js` file. Build the 4 data panels from section 8: Disruptions, Active Travelers, Escalations, and Travelers by Destination chart. Follow the EXACT code examples in section 8 - copy the code blocks exactly as shown.
 
 ---
 

package/package.json

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