@schandlergarcia/sf-web-components 1.9.64 → 1.9.65

package/CHANGELOG.md

@@ -5,15 +5,7 @@ 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.64] - 2026-04-01
-
-### Added
-- **New phase-based build system** - Self-contained step-by-step build instructions
-  - `.a4drules/phases/phase-1-layout.md` - Layout setup with code template
-  - `.a4drules/phases/phase-2-components.md` - Component implementation with exact imports
-  - `.a4drules/phases/phase-3-live-data.md` - GraphQL integration
-  - `.a4drules/phases/phase-4-agent.md` - Eva ChatBar implementation
-  - These phase files replace the scattered instructions in multiple skill/feature files
+## [1.9.65] - 2026-04-01
 
 ### Fixed
 - **6 data bugs in engine-sample-data.js**:
@@ -27,20 +19,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Updated
 - **PRD (engine-command-center-prd.md)**:
   - Fixed "Sarah Chen" → "Priya Patel" in section 8c escalation example
-  - Rewrote section 13 build prompts to reference new phase files
+  - Updated section 13 build prompts
 - **Simplified .a4drules documentation** - Removed redundancy and contradictions:
-  - `features/engine-dashboard-rule.md` - Reduced from 310 to ~65 lines (non-negotiable constraints + phase routing)
+  - `features/engine-dashboard-rule.md` - Reduced from 310 to ~65 lines (non-negotiable constraints)
   - `features/command-center-dashboard-rule.md` - Reduced from ~100 to ~30 lines (10 core constraints)
   - `features/pre-code-checklist.md` - Reduced from 216 to ~25 lines (removed auto-load)
-  - `features/phase2-data-pattern.md` - Reduced from 167 to ~20 lines (redirects to phase file)
+  - `features/phase2-data-pattern.md` - Reduced from 167 to ~20 lines
   - `skills/command-center-builder/SKILL.md` - Fixed map layout contradiction, removed validator
   - `skills/command-center-builder/page-layout.md` - Fixed map layout contradiction
   - `skills/command-center-builder/completion-checklist.md` - Replaced validator "MUST run" with "DO NOT run"
-  - `skills/command-center-builder/improved-build-process.md` - Reduced from 341 to ~30 lines (redirects to phases)
+  - `skills/command-center-builder/improved-build-process.md` - Reduced from 341 to ~30 lines
   - `skills/command-center-project/SKILL.md` - Fixed file path contradiction (src/components/pages/ → src/pages/)
   - `skills/command-center-guide/SKILL.md` - Reduced from 270 to ~45 lines (simplified routing guide)
 
-**Context:** The phase-based system provides self-contained, copy-paste ready build instructions that eliminate the confusion caused by scattered, contradictory guidance across multiple files. All documentation now points to the phase files as the source of truth.
+**Context:** Streamlined documentation to eliminate confusion caused by scattered, contradictory guidance across multiple files.
+
+## [1.9.64] - 2026-04-01
+
+### Updated
+- **Documentation improvements** - Synced latest changes from react-cursor-1 including data bug fixes and simplified .a4drules structure
 
 ## [1.9.63] - 2026-04-01
 

package/package.json

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

package/.a4drules/phases/phase-1-layout.md

@@ -1,187 +0,0 @@
----
-name: engine-phase-1-layout
-description: >-
-  Phase 1 of the Engine Travel Command Center build. Creates the complete layout
-  skeleton with header, hero map, glass overlays, flight strip, and placeholder
-  data panels. Use this when the build prompt says "Phase 1" or "scaffold".
----
-
-# Phase 1: Layout & Structure
-
-**Source of truth:** `engine-command-center-prd.md` (sections 3–6)
-
-**Goal:** Build the complete layout skeleton in one file. The hero map, glass KPI overlays, and flight status strip are real — only the 4 data panels below are placeholders.
-
-## File Setup
-
-Create `src/pages/EngineDashboard.tsx` (.tsx, NOT .jsx).
-
-## Code Template
-
-Copy this template, then fill in the `{/* TODO */}` sections using the PRD:
-
-```tsx
-import { GeoMap, BaseCard } from "@/components/library";
-import { useThemeMode } from "@/components/library/theme/AppThemeProvider";
-import {
-  GlobeAltIcon,
-  SunIcon,
-  MoonIcon,
-  BellIcon,
-  UsersIcon,
-  BanknotesIcon,
-  ShieldCheckIcon,
-  SparklesIcon,
-} 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 ─────────────────────────────────────────── */}
-      <header className="sticky top-0 z-50 flex h-12 items-center justify-between border-b border-slate-800 bg-slate-900 dark:bg-slate-950 px-4">
-        {/* Left: logo + title */}
-        <div className="flex items-center gap-2">
-          <div className="flex h-7 w-7 items-center justify-center rounded-md bg-brand-600">
-            <GlobeAltIcon className="h-4 w-4 text-slate-50" />
-          </div>
-          <span className="text-sm font-bold tracking-wider text-slate-50">ENGINE</span>
-          <span className="mx-2 h-4 w-px bg-slate-700" />
-          <span className="text-sm font-medium text-slate-300">Travel Command Center</span>
-        </div>
-        {/* Right: actions */}
-        <div className="flex items-center gap-3">
-          {/* ChatBar goes here in Phase 4 */}
-          <button className="relative text-slate-400 hover:text-slate-200">
-            <BellIcon className="h-5 w-5" />
-            <span className="absolute -right-1 -top-1 flex h-4 w-4 items-center justify-center rounded-full bg-rose-500 text-[10px] font-bold text-slate-50">3</span>
-          </button>
-          <button onClick={toggle} className="text-slate-400 hover:text-slate-200">
-            {mode === "dark" ? <SunIcon className="h-5 w-5" /> : <MoonIcon className="h-5 w-5" />}
-          </button>
-        </div>
-      </header>
-
-      {/* ── HERO MAP ───────────────────────────────────────────── */}
-      <div className="relative h-[520px]">
-        <GeoMap
-          width={960}
-          height={520}
-          theme={mode === "dark" ? "dark" : "light"}
-          className="h-full w-full"
-        />
-
-        {/* Glass KPI overlays — 4 pills, absolute top-left */}
-        <div className="absolute left-3 top-3 flex flex-wrap gap-2">
-          {[
-            { icon: UsersIcon, label: "Active Travelers", value: "8" },
-            { icon: BanknotesIcon, label: "Spend MTD", value: "$128.4K" },
-            { icon: ShieldCheckIcon, label: "Compliance", value: "75%" },
-            { icon: SparklesIcon, label: "Eva Resolved", value: "6 resolved" },
-          ].map((kpi) => (
-            <div
-              key={kpi.label}
-              className="flex items-center gap-2 rounded-lg border border-white/10 bg-black/40 px-3 py-1.5 backdrop-blur-md"
-            >
-              <kpi.icon className="h-4 w-4 text-brand-400" />
-              <div>
-                <div className="text-[10px] uppercase tracking-wider text-slate-300">{kpi.label}</div>
-                <div className="text-sm font-semibold text-slate-50">{kpi.value}</div>
-              </div>
-            </div>
-          ))}
-        </div>
-
-        {/* Flight status strip — absolute bottom */}
-        <div className="absolute bottom-3 left-3 right-3 flex gap-2 overflow-x-auto">
-          {[
-            { flight: "BA 286", route: "SFO → LHR", status: "In Air" },
-            { flight: "NH 109", route: "JFK → NRT", status: "In Air" },
-            { flight: "LH 431", route: "ORD → BER", status: "Delayed" },
-            { flight: "SQ 37",  route: "LAX → SIN", status: "Boarding" },
-          ].map((f) => (
-            <div
-              key={f.flight}
-              className="flex shrink-0 items-center gap-2 rounded-lg border border-white/10 bg-black/40 px-3 py-1.5 backdrop-blur-md"
-            >
-              <span className="text-sm font-medium text-slate-50">{f.flight}</span>
-              <span className="text-xs text-slate-400">{f.route}</span>
-              <span
-                className={`rounded-full px-2 py-0.5 text-[10px] font-semibold ${
-                  f.status === "In Air"   ? "bg-green-500/20 text-green-400" :
-                  f.status === "Delayed"  ? "bg-amber-500/20 text-amber-400" :
-                  f.status === "Boarding" ? "bg-sky-500/20 text-sky-400" :
-                                           "bg-slate-500/20 text-slate-400"
-                }`}
-              >
-                {f.status}
-              </span>
-            </div>
-          ))}
-        </div>
-      </div>
-
-      {/* ── DATA PANELS (placeholders) ─────────────────────────── */}
-      <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) + Monthly Spend 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">
-                Travel Spend Panel
-              </div>
-            </BaseCard>
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}
-```
-
-## Brand Tokens
-
-Update `src/styles/global.css` — replace the `--color-brand-*` palette inside the `@theme inline` block with the Engine teal palette from PRD section 3. Also add `--color-engine-savings: #16A34A`.
-
-## Wiring (all 3 required)
-
-1. **CommandCenter.tsx** — import `EngineDashboard` from `"../../pages/EngineDashboard"` and render it
-2. **Home.tsx** — import `CommandCenter` and render it
-3. **routes.tsx** — set `Home` as the index route, move `Search` to `/search`
-
-## Constraints (5 only)
-
-1. File MUST be `.tsx` in `src/pages/`
-2. Import ONLY from `@/components/library` and `@heroicons/react`
-3. Colors: slate scale only — NO `text-white`, `text-black`, `bg-black` (exception: `bg-black/40` with opacity is OK for glass)
-4. Full-page scroll — NO `h-screen` on outer container
-5. DO NOT run `npm run dev` or `npm run validate:dashboard` — phase is complete after wiring
-
-## Phase 1 does NOT include
-
-- Sample data (Phase 2)
-- ChatBar / Eva (Phase 4)
-- Salesforce signals like "Powered by..." (Phase 4)
-- Any `npm install` commands

package/.a4drules/phases/phase-2-components.md

@@ -1,176 +0,0 @@
----
-name: engine-phase-2-components
-description: >-
-  Phase 2 of the Engine Travel Command Center build. Replaces placeholder panels
-  with library components wired to pre-existing sample data. Adds map data.
-  Use this when the build prompt says "Phase 2" or "components".
----
-
-# Phase 2: Components & Sample Data
-
-**Source of truth:** `engine-command-center-prd.md` (sections 7–8)
-
-**Goal:** Replace the 4 placeholder data panels with real library components. Add map data (markers, arcs, overlays). The sample data file already exists — just import from it.
-
-## Critical: Data file already exists
-
-`src/data/engine-sample-data.js` is pre-built with ~370 lines of sample data. **DO NOT create a new data file.** Just import from the existing one.
-
-## Imports to add to EngineDashboard.tsx
-
-```tsx
-import {
-  GeoMap,
-  BaseCard,
-  ActivityCard,
-  ChartCard,
-  D3Chart,
-  D3ChartTemplates,
-  Avatar,
-  UIChip,
-} from "@/components/library";
-import useDataSource from "@/components/library/data/useDataSource";
-import {
-  MAP_MARKERS,
-  MAP_ARCS,
-  MAP_OVERLAYS,
-  FLIGHT_STATUS_LIST,
-  TRAVELER_CARDS,
-  DISRUPTION_CARDS,
-  ESCALATION_CARDS,
-  MONTHLY_SPEND,
-  METRICS,
-} from "@/data/engine-sample-data";
-```
-
-## Changes to make
-
-### 1. Hero Map — add data props
-
-```tsx
-<GeoMap
-  width={960}
-  height={520}
-  theme={mode === "dark" ? "dark" : "light"}
-  markers={useDataSource({ sample: MAP_MARKERS, live: [] })}
-  arcs={useDataSource({ sample: MAP_ARCS, live: [] })}
-  overlays={useDataSource({ sample: MAP_OVERLAYS, live: [] })}
-  zoomable
-  className="h-full w-full"
-/>
-```
-
-### 2. Glass KPI overlays — use METRICS
-
-Replace hardcoded KPI values with `METRICS.activeTravelers`, `METRICS.spendMTD`, `METRICS.complianceRate`, `METRICS.evaResolved`.
-
-Use `fmtK()` helper for spend formatting:
-
-```tsx
-function fmtK(n: number) {
-  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
-  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
-  return n.toLocaleString();
-}
-```
-
-### 3. Flight status strip — use FLIGHT_STATUS_LIST
-
-Replace hardcoded flights with `FLIGHT_STATUS_LIST.map(...)`.
-
-### 4. Disruptions Panel (1/3 width) — custom inline component
-
-Replace the placeholder BaseCard. Build a custom panel inside a BaseCard showing only disrupted flights. Each disruption card shows severity dot, flight number, route, traveler, reason, and Eva action.
-
-```tsx
-<BaseCard>
-  <div className="space-y-3 p-1">
-    <h3 className="text-sm font-semibold text-slate-900 dark:text-slate-50">Disruptions</h3>
-    {useDataSource({ sample: DISRUPTION_CARDS, live: [] }).map((d) => (
-      <div key={d.id} className="rounded-lg border border-slate-200 p-3 dark:border-slate-800">
-        <div className="flex items-center gap-2">
-          <span className={`h-2 w-2 rounded-full ${d.severity === "grounded" ? "bg-rose-500" : "bg-amber-500"}`} />
-          <span className="text-sm font-medium text-slate-900 dark:text-slate-50">{d.flight}</span>
-          <span className={`text-xs ${d.severity === "grounded" ? "text-rose-500" : "text-amber-500"}`}>
-            {d.severity} · {d.delayMin}min
-          </span>
-        </div>
-        <div className="mt-1 text-xs text-slate-500 dark:text-slate-400">{d.route} · {d.traveler}</div>
-        <div className="mt-1 text-xs text-slate-500 dark:text-slate-400">{d.reason}</div>
-        <div className="mt-2 flex items-center gap-1 text-xs text-brand-600 dark:text-brand-400">
-          <SparklesIcon className="h-3 w-3" />
-          <span>{d.evaAction}</span>
-        </div>
-      </div>
-    ))}
-  </div>
-</BaseCard>
-```
-
-### 5. Active Travelers (2/3 width) — expandable cards
-
-Replace the placeholder. Use BaseCard with `maxBodyHeight={420}` for internal scroll. Build expandable traveler rows using `useState` for the expanded ID.
-
-Each row: Avatar (initials) + name + department + origin → destination + UIChip for policy status. Click to expand shows 4-col detail grid (Flight, Hotel, Return, Destination).
-
-### 6. Escalations (1/2 width) — ActivityCard in BaseCard
-
-**Copy this exactly from the PRD:**
-
-```tsx
-<BaseCard>
-  <ActivityCard
-    title="Escalations"
-    actions={useDataSource({ sample: ESCALATION_CARDS, live: [] })}
-  />
-</BaseCard>
-```
-
-ActivityCard MUST be wrapped in BaseCard for visible card styling.
-
-### 7. Monthly Spend Trend (1/2 width) — ChartCard + D3Chart
-
-**Copy this exactly from the PRD:**
-
-```tsx
-const spendChartData = useDataSource({
-  sample: MONTHLY_SPEND.map(m => ({ x: m.month, spend: m.amount })),
-  live: [],
-});
-
-<ChartCard
-  title="Travel Spend"
-  subtitle="Monthly trend (6 months)"
-  chart={
-    <D3Chart
-      data={spendChartData}
-      renderChart={D3ChartTemplates.groupedBarChart}
-      options={{
-        xKey: "x",
-        groups: ["spend"],
-        colors: ["#5BC8C8"],
-        barRadius: 6,
-        margin: { top: 20, right: 20, bottom: 40, left: 60 },
-        showGrid: true,
-      }}
-      responsive
-      height={320}
-    />
-  }
-/>
-```
-
-## Constraints (5 only)
-
-1. **DO NOT create a new data file** — import from the existing `src/data/engine-sample-data.js`
-2. Import ONLY from `@/components/library` and `@heroicons/react` — no shadcn, no Lucide, no Recharts
-3. Wrap `ActivityCard` in `BaseCard` (ActivityCard has no card styling by default)
-4. Use `useDataSource({ sample: X, live: [] })` for all data — enables Phase 3 swap
-5. DO NOT run `npm run dev` or `npm run validate:dashboard`
-
-## Phase 2 does NOT include
-
-- Live Salesforce data (Phase 3)
-- ChatBar / Eva (Phase 4)
-- Salesforce signals (Phase 4)
-- Any `npm install` commands

package/.a4drules/phases/phase-3-live-data.md

@@ -1,85 +0,0 @@
----
-name: engine-phase-3-live-data
-description: >-
-  Phase 3 of the Engine Travel Command Center build. Connects the dashboard to
-  live Salesforce Data Cloud via GraphQL. UI stays identical to Phase 2.
-  Use this when the build prompt says "Phase 3" or "real data".
----
-
-# Phase 3: Real Data Integration
-
-**Source of truth:** `engine-command-center-prd.md` (section 13)
-
-**Goal:** Connect the dashboard to live Salesforce data via GraphQL. The UI stays identical to Phase 2 — only the data source changes.
-
-## Approach
-
-The sample data file (`src/data/engine-sample-data.js`) already uses real Salesforce field names (Trip__c, Flight__c, Contact, etc.). Read the file header to understand the schema.
-
-## Custom objects
-
-| Object | Purpose |
-|--------|---------|
-| Contact | Travelers (with Home_Airport__c, Travel_Policy_Tier__c, etc.) |
-| Trip__c | Origin, destination, dates, cost, policy status |
-| Flight__c | Flight number, airports, status, delay, traveler lookup |
-| Booking__c | Upcoming reservations |
-| Disruption__c | Delays, cancellations, severity |
-| Rebooking_Action__c | Eva activity log |
-| Travel_Policy__c | Policy rules and status |
-
-## Implementation steps
-
-### Step 1: Read the sample data file
-
-Read `src/data/engine-sample-data.js` to understand which Salesforce fields are needed for each object.
-
-### Step 2: Use GraphQL skills to create queries and hooks
-
-For each object, use the Salesforce GraphQL skills:
-
-1. Use the `exploring-webapp-graphql-schema` skill to look up the object in `schema.graphql`
-2. Use the `generating-webapp-graphql-read-query` skill to create a typed query
-3. Use the `using-webapp-graphql` skill to create a data hook (e.g., `useTravelers`, `useFlights`)
-
-Each hook returns `{ data, loading, error }`.
-
-### Step 3: Update useDataSource calls
-
-Change each `useDataSource` call to include live data:
-
-```tsx
-// Phase 2 (sample only)
-const travelers = useDataSource({ sample: TRAVELER_CARDS, live: [] });
-
-// Phase 3 (live with sample fallback)
-const { data: liveTravelers, loading, error } = useTravelers();
-const travelers = useDataSource({
-  sample: TRAVELER_CARDS,
-  live: liveTravelers ?? [],
-});
-```
-
-The `useDataSource` hook automatically uses `live` when available, falling back to `sample` on error.
-
-### Step 4: Add loading and error states
-
-Add `loading` and `error` handling to each section. Library card components accept `loading` and `error` props.
-
-## Data strategy
-
-The app uses a sample data cache (`ENABLE_SAMPLE_DATA_CACHE = true` in `src/lib/dataStrategy.ts`) for instant loading and offline capability. This is production-appropriate — build all GraphQL queries and hooks as normal.
-
-## Constraints (5 only)
-
-1. **DO NOT modify UI components** — only change data sources
-2. **DO NOT add DataModeToggle** — live data only (sample is fallback for errors)
-3. Use exact Salesforce field names from the sample data file
-4. Schema file (`schema.graphql`) is pre-built in the repo — no generation needed
-5. DO NOT run `npm run dev` or `npm run validate:dashboard`
-
-## Phase 3 does NOT include
-
-- ChatBar / Eva (Phase 4)
-- Salesforce signals (Phase 4)
-- UI changes of any kind

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

@@ -1,73 +0,0 @@
----
-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`