@schandlergarcia/sf-web-components 1.9.61 → 1.9.63

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

@@ -26,7 +26,7 @@ The Engine dashboard uses a **strict 4-phase build process.** You MUST complete
    - **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)
+   - **Chart:** Bar chart showing monthly spend trend (see PRD Section 8d code block for exact options and data transformation)
    - **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/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.63] - 2026-04-01
+
+### Updated
+- **Synced latest .a4drules and PRD from reactapp4** - Final sync of all documentation
+  - All `.a4drules/features/` updated
+  - All `.a4drules/skills/` updated
+  - All `.a4drules/troubleshooting/` updated
+  - Root `.a4drules/*.md` files updated
+  - `data/engine-command-center-prd.md` updated to latest
+
+## [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

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

@@ -305,30 +305,31 @@ Examples from sample data:
 
 ### 8d. Monthly Spend Trend (1/2 width)
 
-`ChartCard` wrapping a `D3Chart` with `D3ChartTemplates.lineChart`.
+`ChartCard` wrapping a `D3Chart` with `D3ChartTemplates.groupedBarChart` (lineChart doesn't support categorical x-axis).
 
 **CRITICAL: Use this exact code structure:**
 
 ```tsx
+// Transform data to chart format
+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={useDataSource({ sample: MONTHLY_SPEND, live: [] })}
-      renderChart={D3ChartTemplates.lineChart}
+      data={spendChartData}
+      renderChart={D3ChartTemplates.groupedBarChart}
       options={{
-        xKey: "month",
-        yKey: "amount",
-        color: "#5BC8C8",
-        lineWidth: 3,
-        showDots: true,
-        dotRadius: 4,
-        showArea: true,
-        areaOpacity: 0.1,
+        xKey: "x",
+        groups: ["spend"],
+        colors: ["#5BC8C8"],
+        barRadius: 6,
         margin: { top: 20, right: 20, bottom: 40, left: 60 },
         showGrid: true,
-        formatY: (d) => `$${(d / 1000).toFixed(0)}K`,
       }}
       responsive
       height={320}
@@ -337,19 +338,18 @@ Examples from sample data:
 />
 ```
 
-**Data source:** Import `MONTHLY_SPEND` from sample data
+**Data source:** Import `MONTHLY_SPEND` from sample data, transform to chart format
 
 **Requirements:**
-- X-axis: month names (Oct through Mar)
-- Y-axis: spend amount formatted as $XXK
+- X-axis: month names (Oct through Mar) - categorical
+- Y-axis: spend amount in dollars (will show as thousands: 98000, 128000, etc.)
 - 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)
+- Bar color: Engine teal (#5BC8C8)
+- Bar radius: 6 for rounded corners
+- **Data transformation:** map `{ month, amount }` to `{ x, spend }` format inline
 - responsive={true}
 
-**Why this chart:** Shows spend trends over time so travel managers can spot anomalies, budget overruns, or seasonal patterns. Actionable data for financial planning.
+**Why this chart:** Shows spend trends over time so travel managers can spot anomalies, budget overruns, or seasonal patterns. Using bars instead of line because D3 lineChart requires numeric x-axis.
 
 **That's it!** Only 4 panels total: Disruptions, Active Travelers, Escalations, and Monthly Spend Trend.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schandlergarcia/sf-web-components",
-  "version": "1.9.61",
+  "version": "1.9.63",
   "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": {