@schandlergarcia/sf-web-components 1.9.60 → 1.9.62

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

@@ -17,14 +17,16 @@ 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** — 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
+2. **Phase 2: Components + Sample Data** — Replace data panel placeholders with real library components + sample data AND add map 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, ESCALATION_CARDS, DESTINATION_CHART_DATA)
+   - Import dashboard-ready derivatives (MAP_MARKERS, MAP_ARCS, MAP_OVERLAYS, TRAVELER_CARDS, ESCALATION_CARDS, MONTHLY_SPEND)
    - 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)
+   - **FOLLOW THE EXACT CODE EXAMPLES in PRD Section 7 (map) and Section 8c/8d (panels)** - copy the code blocks as shown
+   - **Map data:** Add markers, arcs, overlays to GeoMap to show where travelers are (see PRD Section 7)
+   - **Panel titles:** "Disruptions", "Active Travelers", "Escalations", "Travel Spend"
+   - **Escalations panel:** ActivityCard must be wrapped in BaseCard for visible card styling
+   - **Chart:** Line chart showing monthly spend trend (see PRD Section 8d code block for exact options)
    - **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

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

@@ -85,7 +85,7 @@ export default function EngineDashboard() {
             </div>
           </div>
 
-          {/* Row 2: Escalations (1/2) + Destination Chart (1/2) */}
+          {/* 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">
@@ -94,7 +94,7 @@ export default function EngineDashboard() {
             </BaseCard>
             <BaseCard>
               <div className="flex h-48 items-center justify-center text-slate-400">
-                Travelers by Destination Panel
+                Travel Spend Panel
               </div>
             </BaseCard>
           </div>

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.62] - 2026-04-01
+
+### Added
+- **CLAUDE.md** - Comprehensive guidance for working with the package in Claude Code
+  - Package overview and purpose
+  - Critical explanation of two UI contexts (outer app vs command center)
+  - Architecture and directory structure
+  - Key conventions (component naming, theme hook, data hook)
+  - Development workflow and pre-publish checks
+  - Postinstall and reset script behavior
+  - Important files guide
+  - Common issues and solutions
+  - Testing checklist
+  - Version history summary
+  - Now included in published package (added to files array)
+
+This file provides essential context when opening sf-web-components as a standalone Claude Code project, explaining the architecture, conventions, and common pitfalls (like UIButton vs Button confusion).
+
+## [1.9.61] - 2026-04-01
+
+### Updated
+- **Synced latest .a4drules and PRD from reactapp4** - Pulled latest documentation updates
+  - All `.a4drules/features/` files updated
+  - All `.a4drules/skills/` files updated
+  - All `.a4drules/troubleshooting/` files updated
+  - Root `.a4drules/*.md` files updated
+  - `data/engine-command-center-prd.md` updated to latest version
+
 ## [1.9.60] - 2026-04-01
 
 ### Updated

package/CLAUDE.md

@@ -0,0 +1,258 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with the sf-web-components package.
+
+## Package Overview
+
+**@schandlergarcia/sf-web-components** is an npm package that provides:
+
+1. **React component library** - Pre-built UI components for Salesforce Web Applications
+2. **Templates** - Page templates (Home, Search, NotFound, BlankDashboard) and config templates (routes.tsx, vite.config.ts, dataStrategy.ts)
+3. **Automation** - Postinstall script that sets up consuming projects automatically
+4. **Documentation** - `.a4drules` skills and features for AI-assisted development
+5. **Sample data** - Engine Travel sample data and pre-built GraphQL schema
+6. **Scripts** - Reset scripts, validation scripts, schema generation
+
+**Primary use case:** Building Salesforce Web Applications with React, specifically for:
+- Outer app pages (search, navigation) using shadcn/ui + Tailwind
+- Command Center dashboards using custom library components + HeroUI
+
+## Architecture
+
+### Two UI Contexts (CRITICAL)
+
+The package supports **two distinct UI contexts** that must NOT be mixed:
+
+#### 1. Outer App Context
+- **Files:** `src/pages/Home.tsx`, `src/pages/Search.tsx`, `src/pages/NotFound.tsx` (installed from templates)
+- **Rendered in:** AppLayout wrapper (standard React Router routes)
+- **Components:** shadcn/ui from `@/components/ui/`
+  - `Button` from `@/components/ui/button`
+  - `Input` from `@/components/ui/input`
+  - etc.
+- **Icons:** Lucide React (`lucide-react`)
+- **Styling:** Neutral shadcn theme (slate colors, no Engine branding)
+- **File type:** `.tsx`
+
+#### 2. Command Center Context
+- **Files:** Dashboard pages in `src/pages/` (e.g., BlankDashboard, EngineDashboard)
+- **Rendered in:** CommandCenter wrapper with `.heroui-scope` class
+- **Components:** Library components from `@/components/library`
+  - `UIButton` from `@/components/library/ui/UIButton`
+  - `UIInput` from `@/components/library/ui/UIInput`
+  - `MetricCard`, `ChartCard`, `ListCard`, `TableCard`, etc.
+- **Icons:** Heroicons (`@heroicons/react`)
+- **Styling:** Engine brand colors (teal #5BC8C8, coral, orange) inside `.heroui-scope`
+- **File type:** `.jsx` or `.tsx`
+
+**Common mistake:** Using UIButton/UIInput in outer app pages or shadcn Button/Input in command center dashboards. Check `.a4drules/features/pre-code-checklist.md` for validation rules.
+
+### Package Structure
+
+```
+sf-web-components/
+├── src/
+│   ├── components/
+│   │   ├── library/           # Command center components (MetricCard, ChartCard, etc.)
+│   │   │   ├── cards/
+│   │   │   ├── charts/
+│   │   │   ├── ui/            # UIButton, UIInput, etc.
+│   │   │   ├── theme/         # AppThemeProvider, useThemeMode
+│   │   │   ├── data/          # useDataSource, DataModeProvider
+│   │   │   └── index.jsx      # Barrel export
+│   │   └── workspace/         # CommandRegistry, ComponentRegistry
+│   ├── templates/
+│   │   ├── pages/             # Home.tsx.template, Search.tsx.template, etc.
+│   │   ├── config/            # routes.tsx.template, vite.config.ts.template
+│   │   ├── lib/               # dataStrategy.ts.template
+│   │   └── workspace/         # CommandCenter.tsx.template
+│   ├── lib/                   # Utilities (utils.ts)
+│   └── styles/                # global.css with Engine brand tokens
+├── scripts/
+│   ├── postinstall.mjs        # Runs after npm install in consuming projects
+│   ├── reset-command-center.sh
+│   ├── validate-dashboard.sh
+│   └── verify-consistency.sh
+├── data/
+│   ├── engine-sample-data.js
+│   ├── schema.graphql
+│   └── engine-command-center-prd.md
+└── .a4drules/
+    ├── features/              # Dashboard rules, engine-dashboard-rule, etc.
+    ├── skills/                # component-library, command-center-builder, etc.
+    ├── troubleshooting/       # Common issues and solutions
+    ├── validation-requirements.md
+    ├── webapp-data.md
+    └── webapp-ui.md
+```
+
+## Key Conventions
+
+### Component Naming
+- **Library components** (command center): `UIButton`, `UIInput`, `MetricCard`, `ChartCard`
+- **shadcn components** (outer app): `Button`, `Input`, `Card` from `@/components/ui/`
+
+### Theme Hook
+- **Correct:** `import { useThemeMode } from "@/components/library/theme/AppThemeProvider"`
+- **Wrong:** `import useAppTheme from ...` (does not exist)
+- **Usage:** `const { mode, toggle } = useThemeMode();`
+
+### Data Hook
+- **Pattern:** Use `useDataSource` for instant loading with sample data cache
+- **Example:**
+  ```javascript
+  import useDataSource from "@/components/library/data/useDataSource";
+  
+  const travelers = useDataSource({
+    sample: SAMPLE_TRAVELERS,
+    live: liveTravelers ?? []
+  });
+  ```
+- **Configuration:** `src/lib/dataStrategy.ts` controls `ENABLE_SAMPLE_DATA_CACHE`
+
+### File Extensions
+- **Outer app pages:** `.tsx`
+- **Command center dashboards:** `.jsx` or `.tsx` (`.jsx` preferred per dashboard rules)
+
+## Working with the Package
+
+### Development Workflow
+
+1. **Make changes** to components, templates, or documentation
+2. **Update version:** `npm version patch` (or minor/major)
+3. **Update CHANGELOG.md** with:
+   - Version number
+   - Date
+   - What changed and why
+   - Context for the change
+4. **Build:** `npm run build`
+5. **Verify:** `npm run verify` (checks consistency)
+6. **Publish:** `npm publish` (runs pre-publish checks automatically)
+
+### Pre-Publish Checks
+
+The `scripts/pre-publish-check.sh` runs automatically before publishing and verifies:
+1. Consistency between code, docs, and templates
+2. CHANGELOG.md has entry for current version
+3. Component naming conventions (UIButton.tsx exists, Button.tsx doesn't in library/ui/)
+4. Build succeeds
+5. Documentation files exist
+6. package.json files array includes necessary directories
+
+### Postinstall Behavior
+
+When a project installs this package, `scripts/postinstall.mjs` automatically:
+
+1. **Copies component library** to `src/components/library/`
+2. **Copies lib utilities** to `src/lib/`
+3. **Copies types** to `src/types/`
+4. **Copies workspace files** to `src/components/workspace/`
+5. **Installs page templates** to `src/pages/` (Home.tsx, Search.tsx, NotFound.tsx, BlankDashboard.tsx)
+6. **Updates imports** in existing files (changes package imports to local `@/components/library` imports)
+7. **Copies sample data** to `src/data/engine-sample-data.js`
+8. **Copies schema** to root `schema.graphql`
+9. **Copies PRD** to root `engine-command-center-prd.md`
+10. **Installs config files** (routes.tsx, vite.config.ts, dataStrategy.ts) if they don't exist
+11. **Adds npm scripts** to package.json (reset:command-center, validate:dashboard, graphql:schema:sample)
+12. **Copies .a4drules** to project root for AI assistant discoverability
+
+**Important:** Templates are **always overwritten** to ensure latest versions, except for config files (vite.config.ts, dataStrategy.ts) which only install if missing.
+
+### Reset Script
+
+The `scripts/reset-command-center.sh` provides a clean baseline for projects:
+
+- Removes custom dashboard pages
+- Restores BlankDashboard.tsx
+- Updates CommandCenter.tsx to render BlankDashboard
+- Restores Home.tsx with Account Search page
+- Restores Search.tsx placeholder
+- Updates routes.tsx to include Home, /accounts, and /accounts/:recordId
+- Updates appLayout.tsx with nav bar
+- Clears Vite cache
+- Restores Engine-branded global.css
+- Restores sample data and schema
+
+## Important Files
+
+### CHANGELOG.md
+Complete history of all changes. ALWAYS update when making changes. Include:
+- What changed
+- Why it changed
+- Context for the change
+- Impact on consuming projects
+
+### .a4drules/
+AI assistant documentation. Key files:
+- `features/engine-dashboard-rule.md` - How to build Engine Travel Command Center
+- `features/command-center-dashboard-rule.md` - Dashboard development rules
+- `features/pre-code-checklist.md` - Pre-implementation validation
+- `skills/component-library/` - Component API reference
+- `validation-requirements.md` - Validation rules
+- `webapp-data.md` - Data access patterns (GraphQL, REST, SDK usage)
+- `webapp-ui.md` - UI platform rules
+
+### data/engine-command-center-prd.md
+Product Requirements Document for Engine Travel Command Center. Defines:
+- Product overview and users
+- Brand tokens (Engine teal #5BC8C8, etc.)
+- Layout structure (visualization-hero pattern)
+- Component sections and data model
+- Phase-by-phase build instructions
+
+### src/components/library/theme/AppThemeProvider.jsx
+Theme provider with dark mode toggle. Exports:
+- **Default:** `AppThemeProvider` component
+- **Named:** `useThemeMode` hook
+
+### src/components/library/data/useDataSource.js
+Hook for sample/live data switching via `ENABLE_SAMPLE_DATA_CACHE` flag.
+
+## Common Issues
+
+### TypeScript Errors
+If you see TypeScript errors about missing exports:
+1. Check the actual file to see what's exported
+2. Don't trust TypeScript's suggestions blindly (it may suggest wrong import patterns)
+3. Refer to `.a4drules/skills/component-library/SKILL.md` for correct import patterns
+
+### Component Confusion
+If agents mix up UIButton (library) vs Button (shadcn):
+1. Check `.a4drules/features/pre-code-checklist.md` for validation rules
+2. Outer app pages should NEVER import from `@/components/library`
+3. Command center dashboards should NEVER import from `@/components/ui/`
+
+### Routes Not Working
+If routes show 404:
+1. Check routes.tsx imports match installed file locations
+2. Home should point to `./pages/Home` (not `__examples__`)
+3. Accounts should point to `./features/object-search/__examples__/pages/AccountSearch`
+4. Make sure `handle.showNavBar: true` is set for pages that need nav
+
+### Missing Nav Bar
+Routes need `handle: { showInNavigation: true, showNavBar: true }` for nav bar to appear.
+
+## Testing
+
+Before publishing:
+1. Test in a real project (reactapp4, vibes3, etc.)
+2. Run `npm install @schandlergarcia/sf-web-components@latest`
+3. Verify postinstall behavior
+4. Check templates are correct
+5. Verify .a4drules are accessible
+6. Test reset script: `npm run reset:command-center`
+7. Test validation: `npm run validate:dashboard`
+
+## Version History
+
+See CHANGELOG.md for complete history. Recent major changes:
+- v1.9.55 - Fixed UIButton/Button confusion in templates
+- v1.9.56 - Fixed reset script 404 errors
+- v1.9.57 - Restored "Browse All Accounts" button
+- v1.9.58 - Fixed reset routes pointing to wrong Home file
+- v1.9.59 - Restored navigation bar (showNavBar flag)
+- v1.9.60-61 - Synced .a4drules and PRD from reactapp4
+
+## Current Version
+
+Run `node -p "require('./package.json').version"` to get current version.

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

@@ -99,8 +99,8 @@ This dashboard uses the **visualization-hero** layout. The live flight map is th
 │  └────────────────┘ └────────────────────────────┘         │  ↕
 │                                                             │  ↕
 │  ┌─── 1/2 ───────┐ ┌─── 1/2 ────────────────────┐         │  ↕
-│  │ Escalations    │ │ Travelers by Destination    │         │  ↕
-│  │ (ActivityCard) │ │ (ChartCard + D3Chart)       │         │  ↕
+│  │ Escalations    │ │ Travel Spend (Monthly)      │         │  ↕
+│  │ (ActivityCard) │ │ (ChartCard + D3Chart line)  │         │  ↕
 │  └────────────────┘ └────────────────────────────┘         │  ↕
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -215,20 +215,26 @@ The `ChatBar` replaces any FAB or sliding panel. It opens inline as a command pa
 
 **Component:** `GeoMap` (from `@/components/library`)
 
-```jsx
+**Phase 1:** Render GeoMap with NO data props (no markers/arcs/overlays)
+**Phase 2:** Add markers, arcs, and overlays from sample data to show where travelers are
+
+```tsx
+import { MAP_MARKERS, MAP_ARCS, MAP_OVERLAYS } from "@/data/engine-sample-data";
+
+// Phase 2 - with map data
 <GeoMap
   width={960}
   height={520}
   theme={mode === "dark" ? "dark" : "light"}
-  markers={markers}
-  arcs={arcs}
-  overlays={overlays}
+  markers={useDataSource({ sample: MAP_MARKERS, live: [] })}
+  arcs={useDataSource({ sample: MAP_ARCS, live: [] })}
+  overlays={useDataSource({ sample: MAP_OVERLAYS, live: [] })}
   zoomable
   className="h-full w-full"
 />
 ```
 
-**Markers:** One per city (origin and destination). Each marker: `{ id, lon, lat, label, active: true }`.
+**Markers:** One per city (origin and destination). Each marker: `{ id, lon, lat, label, active: true }`. Shows where travelers are located.
 
 **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.
 
@@ -273,17 +279,19 @@ Each traveler row:
 
 ### 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`)
+**CRITICAL: ActivityCard has no card styling by default. Must wrap in BaseCard for visible card background.**
 
 ```tsx
-<ActivityCard
-  title="Escalations"
-  actions={useDataSource({ sample: ESCALATION_CARDS, live: [] })}
-/>
+<BaseCard>
+  <ActivityCard
+    title="Escalations"
+    actions={useDataSource({ sample: ESCALATION_CARDS, live: [] })}
+  />
+</BaseCard>
 ```
 
+**Data source:** Import `ESCALATION_CARDS` from sample data (alias of `EVA_ACTIONS`)
+
 Each escalation has:
 - Title (issue description)
 - Subtitle (details + context)
@@ -295,28 +303,32 @@ Examples from sample data:
 - "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)
+### 8d. Monthly Spend Trend (1/2 width)
 
-`ChartCard` wrapping a `D3Chart` with `D3ChartTemplates.groupedBarChart`.
+`ChartCard` wrapping a `D3Chart` with `D3ChartTemplates.lineChart`.
 
 **CRITICAL: Use this exact code structure:**
 
 ```tsx
 <ChartCard
-  title="Travelers by Destination"
-  subtitle="Active trips by city"
+  title="Travel Spend"
+  subtitle="Monthly trend (6 months)"
   chart={
     <D3Chart
-      data={destinationData}
-      renderChart={D3ChartTemplates.groupedBarChart}
+      data={useDataSource({ sample: MONTHLY_SPEND, live: [] })}
+      renderChart={D3ChartTemplates.lineChart}
       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 },
+        xKey: "month",
+        yKey: "amount",
+        color: "#5BC8C8",
+        lineWidth: 3,
+        showDots: true,
+        dotRadius: 4,
+        showArea: true,
+        areaOpacity: 0.1,
+        margin: { top: 20, right: 20, bottom: 40, left: 60 },
         showGrid: true,
+        formatY: (d) => `$${(d / 1000).toFixed(0)}K`,
       }}
       responsive
       height={320}
@@ -325,16 +337,21 @@ Examples from sample data:
 />
 ```
 
+**Data source:** Import `MONTHLY_SPEND` from sample data
+
 **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)
+- X-axis: month names (Oct through Mar)
+- Y-axis: spend amount formatted as $XXK
+- Height: 320px
+- Line color: Engine teal (#5BC8C8)
+- Line width: 3px
+- Show dots at data points (radius: 4)
+- Show filled area under line (opacity: 0.1)
 - responsive={true}
 
-**That's it!** Only 4 panels total: Disruptions, Active Travelers, Escalations, and Travelers by Destination.
+**Why this chart:** Shows spend trends over time so travel managers can spot anomalies, budget overruns, or seasonal patterns. Actionable data for financial planning.
+
+**That's it!** Only 4 panels total: Disruptions, Active Travelers, Escalations, and Monthly Spend Trend.
 
 ---
 
@@ -406,9 +423,7 @@ Mandatory on every element. The dashboard must work in both light and dark mode
 
 **Escalation** — `id`, `title`, `subtitle`, `status` (complete | working | pending), `timestamp`
 
-**Monthly Spend** — `{ x: month, y: amount }` array
-
-**Destination Chart** — `{ x: city, travelers: count }` array
+**Monthly Spend** — `{ month: string, amount: number }` array. Six months of travel spend data (Oct through Mar). Amounts in dollars, typically $98K-$156K range.
 
 **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.
 
@@ -432,7 +447,9 @@ 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 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.
+> 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 Monthly Spend Trend chart. Follow the EXACT code examples in section 8 - copy the code blocks exactly as shown.
+>
+> **Add map data:** Import MAP_MARKERS, MAP_ARCS, MAP_OVERLAYS from sample data and pass to GeoMap component (see Section 7). The map should show where travelers are with markers for cities, arcs for flight routes, and overlays for disruptions.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schandlergarcia/sf-web-components",
-  "version": "1.9.60",
+  "version": "1.9.62",
   "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,6 +38,7 @@
     "CONTRIBUTING.md",
     "ARCHITECTURE.md",
     "QUICK-REFERENCE.md",
+    "CLAUDE.md",
     ".a4drules"
   ],
   "scripts": {