@schandlergarcia/sf-web-components 1.9.26 → 1.9.28

package/INSTALL.md

@@ -0,0 +1,200 @@
+# Installation Guide
+
+Quick start guide for installing `@schandlergarcia/sf-web-components` in your Salesforce web application.
+
+## Prerequisites
+
+- Salesforce web application created with `sf webapp generate --template react-ts`
+- Node.js 18+ and npm installed
+- Tailwind CSS v4 configured in your project
+
+## Installation Steps
+
+### 1. Navigate to Your Web App
+
+```bash
+cd force-app/main/default/webapplications/YOUR_APP_NAME
+```
+
+### 2. Install the Package
+
+```bash
+npm install @schandlergarcia/sf-web-components@latest
+```
+
+The postinstall script runs automatically and:
+- ✅ Copies 102+ component files to `src/components/library/`
+- ✅ Installs page templates to `src/pages/`
+- ✅ Installs workspace files to `src/components/workspace/`
+- ✅ Copies AI assistant rules to project root `.a4drules/`
+- ✅ Adds `reset:command-center` and `validate:dashboard` scripts
+- ✅ Updates imports in existing files
+
+### 3. Install Type Definitions
+
+```bash
+npm install --save-dev @types/d3 @types/topojson-client
+```
+
+### 4. Verify Installation
+
+```bash
+npm run build
+npm run dev
+```
+
+Visit `http://localhost:5173` - you should see the CommandCenter with BlankDashboard.
+
+## What You Get
+
+After installation:
+
+```
+src/
+├── components/
+│   ├── library/           # 102+ UI components
+│   │   ├── ui/            # Buttons, inputs, cards, alerts
+│   │   ├── cards/         # MetricCard, ChartCard, TableCard, etc.
+│   │   ├── charts/        # D3Chart, GeoMap
+│   │   ├── forms/         # FormRenderer, FormField
+│   │   ├── filters/       # SearchFilter, SelectFilter
+│   │   └── ...
+│   └── workspace/
+│       └── CommandCenter.tsx  # Dashboard wrapper
+├── pages/
+│   ├── Home.tsx           # Renders CommandCenter
+│   ├── BlankDashboard.tsx # Empty template
+│   ├── Search.tsx         # Search interface
+│   └── NotFound.tsx       # 404 page
+├── lib/
+│   └── utils.ts           # Utility functions
+└── types/
+    └── conversation.ts    # AgentforceConversationClient types
+
+package.json               # Added scripts:
+                          # - reset:command-center
+                          # - validate:dashboard
+
+.a4drules/                # AI assistant rules (at project root)
+├── skills/
+│   └── command-center-builder/
+│       └── SKILL.md
+└── features/
+    └── command-center-dashboard-rule.md
+```
+
+## Next Steps
+
+### Option 1: Build a Dashboard with AI
+
+Have an AI assistant (Agentforce, Claude, etc.) build your dashboard:
+
+```
+Build me a Sales Dashboard with KPI metrics, revenue chart, and top accounts table
+```
+
+The AI will:
+1. Load the command-center-builder skill
+2. Create your dashboard file in `src/pages/`
+3. Wire it to CommandCenter
+4. Update Home.tsx
+5. Validate with `npm run validate:dashboard`
+
+### Option 2: Build Manually
+
+```bash
+# 1. Create dashboard file
+cat > src/pages/MyDashboard.tsx << 'EOF'
+import { MetricCard, ChartCard } from '@/components/library';
+
+export default function MyDashboard() {
+  return (
+    <div className="space-y-6 p-6">
+      <div className="grid grid-cols-3 gap-6">
+        <MetricCard title="Revenue" value="$1.2M" change="+12%" changeType="positive" />
+        <MetricCard title="Users" value={1284} change="+8%" changeType="positive" />
+        <MetricCard title="Conversion" value="3.2%" change="-0.5%" changeType="negative" />
+      </div>
+    </div>
+  );
+}
+EOF
+
+# 2. Wire to CommandCenter
+# Edit src/components/workspace/CommandCenter.tsx
+# Change: import BlankDashboard from "../../pages/BlankDashboard";
+# To:     import MyDashboard from "../../pages/MyDashboard";
+# Change: <BlankDashboard />
+# To:     <MyDashboard />
+
+# 3. Update Home
+# Home.tsx should already render CommandCenter
+
+# 4. Validate
+npm run validate:dashboard
+```
+
+## Useful Commands
+
+```bash
+# Development
+npm run dev                  # Start dev server
+npm run build                # Build for production
+
+# Dashboard Management
+npm run reset:command-center # Reset to blank state
+npm run validate:dashboard   # Check dashboard rules
+
+# GraphQL (if using Salesforce data)
+npm run graphql:schema       # Fetch schema
+npm run graphql:codegen      # Generate types
+```
+
+## Troubleshooting
+
+### Postinstall didn't run
+
+```bash
+node node_modules/@schandlergarcia/sf-web-components/scripts/postinstall.mjs
+```
+
+### Build errors about missing D3 types
+
+```bash
+npm install --save-dev @types/d3 @types/topojson-client
+```
+
+### Home page shows blank/wrong content
+
+```bash
+# Re-run postinstall to restore templates
+node node_modules/@schandlergarcia/sf-web-components/scripts/postinstall.mjs
+```
+
+### AI assistant not following rules
+
+Check that `.a4drules/` exists at your **project root** (not in the webapp directory):
+
+```bash
+# From webapp directory
+ls ../../../../../.a4drules/skills/command-center-builder/SKILL.md
+```
+
+If missing, re-run postinstall:
+
+```bash
+node node_modules/@schandlergarcia/sf-web-components/scripts/postinstall.mjs
+```
+
+## Support
+
+- **Documentation:** [README.md](./README.md)
+- **Issues:** [GitHub Issues](https://github.com/schandlergarcia/sf-web-components/issues)
+- **Package:** [npm](https://www.npmjs.com/package/@schandlergarcia/sf-web-components)
+
+## Next Steps
+
+- Read the [Component Documentation](./README.md#using-the-dashboard-framework)
+- Check [AI Assistant Rules](./.a4drules/skills/command-center-builder/SKILL.md) (after install)
+- Browse example pages in `src/pages/`
+- Explore component library in `src/components/library/`

package/README.md

@@ -57,13 +57,13 @@ The postinstall script automatically:
 - Chat components (message UI, typing indicators, suggestions)
 
 ✅ **Installs complete routes configuration** at `src/routes.tsx`
-- Home page with account search
+- `/` (Home) - Renders CommandCenter (dashboard wrapper)
 - `/accounts` - Account search with filters and sorting
 - `/accounts/:recordId` - Account detail page
-- NotFound page
+- `*` (NotFound) - 404 error page
 
 ✅ **Installs 4 page templates** to `src/pages/`
-- `Home.tsx` - Search interface with UIButton and UIInput
+- `Home.tsx` - Renders CommandCenter (dashboard wrapper)
 - `NotFound.tsx` - 404 error page
 - `Search.tsx` - Generic search page
 - `BlankDashboard.tsx` - Empty dashboard template
@@ -77,6 +77,63 @@ The postinstall script automatically:
 ✅ **Installs workspace components** to `src/components/workspace/`
 - `CommandCenter.tsx` - Dashboard wrapper with theme and data providers
 
+✅ **Adds npm scripts** to your `package.json`
+- `reset:command-center` - Reset to blank dashboard state
+- `validate:dashboard` - Validate dashboard files against rules
+
+✅ **Copies AI assistant rules** to project root `.a4drules/`
+- `skills/` - Step-by-step guides for AI assistants (Agentforce, Claude, etc.)
+- `features/` - Feature-specific implementation rules
+- Enables AI assistants to build dashboards correctly
+
+---
+
+## Building Dashboards
+
+### With AI Assistants (Agentforce, Claude, etc.)
+
+After installation, AI assistants can build complete dashboards for you:
+
+**Example prompt:**
+```
+Build me a Fleet Management Command Center dashboard with:
+- KPI metrics for total vehicles, active trips, maintenance alerts
+- World map showing vehicle locations
+- List of recent trips
+- Status panel for vehicle health
+```
+
+The AI assistant will:
+1. ✅ Load the command-center-builder skill
+2. ✅ Create `src/pages/FleetDashboard.tsx` (complete, valid TypeScript)
+3. ✅ Update `CommandCenter.tsx` to import it
+4. ✅ Update `Home.tsx` to render CommandCenter
+5. ✅ Run `npm run validate:dashboard` and fix all errors
+6. ✅ Report when complete
+
+**Result:** Working dashboard at `/` using only library components.
+
+### Manual Dashboard Development
+
+If you prefer to build dashboards manually:
+
+```bash
+# 1. Create your dashboard file
+touch src/pages/MyDashboard.tsx
+
+# 2. Import and use library components
+# (see examples below)
+
+# 3. Wire it to CommandCenter
+# Edit src/components/workspace/CommandCenter.tsx
+
+# 4. Update Home to render CommandCenter
+# Edit src/pages/Home.tsx
+
+# 5. Validate your work
+npm run validate:dashboard
+```
+
 ---
 
 ## Using the Dashboard Framework
@@ -289,12 +346,12 @@ npm install
 npm run build
 ```
 
-### Reset Command Center (All Apps)
+### Reset Command Center
 
 This script resets any app back to the blank dashboard baseline state:
 
 ```bash
-# This script resets the command center to the blank dashboard template
+# Reset the command center to the blank dashboard template
 npm run reset:command-center
 
 # Or run directly:
@@ -302,15 +359,40 @@ bash node_modules/@schandlergarcia/sf-web-components/scripts/reset-command-cente
 ```
 
 **What it does:**
-- Removes custom dashboard pages (including those created at SFDX project root)
-- Reinstalls BlankDashboard.tsx with EmptyState
-- Resets CommandCenter.tsx (preserves theme mode)
-- Updates Home.tsx to render search interface
-- Creates Search.tsx for search interface at `/search` route
-- Resets routes to baseline configuration
-- Preserves: component library, authentication, all dependencies
+- Removes custom dashboard pages from `src/pages/` (EngineDashboard.tsx, FleetDashboard.tsx, etc.)
+- Reinstalls BlankDashboard.tsx with EmptyState ("Bespoke App Template" message)
+- Resets CommandCenter.tsx to import BlankDashboard (preserves theme mode)
+- Updates Home.tsx to render search interface (not CommandCenter)
+- Creates Search.tsx for search interface
+- Resets routes.tsx to baseline configuration
+- Preserves: component library, workspace files, authentication, all dependencies
+
+**Result:** Home route (`/`) displays the search interface. CommandCenter exists but is not wired to any route until you create a dashboard.
+
+### Validate Dashboard
+
+After building a dashboard, validate it meets all requirements:
+
+```bash
+# Run the dashboard validator
+npm run validate:dashboard
+
+# Or run directly:
+bash node_modules/@schandlergarcia/sf-web-components/scripts/validate-dashboard.sh
+```
+
+**What it checks:**
+- Files use `.tsx` extension (not `.jsx`)
+- CommandCenter.tsx imports a real dashboard (not BlankDashboard)
+- No hand-rolled HTML cards (must use library components)
+- No forbidden colors (`text-white`, `text-black`, `bg-black`)
+- No inline `style={{}}` or `<style>` tags
+- Dashboard uses `useDataSource` for sample/live data
+- No navigation elements (`<nav>`) inside dashboard
+- Max 4 metrics per row
+- All JSX tags properly closed
 
-**Result:** Home route (`/`) displays the search interface (baseline state)
+**Exit codes:** 0 = pass, 1 = errors found (must fix before dashboard is complete)
 
 ---
 
@@ -378,16 +460,20 @@ Available npm scripts in the consuming application:
 
 ```bash
 # Development
-npm run dev              # Start Vite dev server
-npm run build            # TypeScript check + Vite build
-npm run lint             # Run ESLint
+npm run dev                  # Start Vite dev server
+npm run build                # TypeScript check + Vite build
+npm run lint                 # Run ESLint
+
+# Dashboard Development
+npm run reset:command-center # Reset to blank dashboard state
+npm run validate:dashboard   # Validate dashboard files against rules
 
 # GraphQL (if using)
-npm run graphql:schema   # Fetch GraphQL schema from Salesforce org
-npm run graphql:codegen  # Generate TypeScript types from schema
+npm run graphql:schema       # Fetch GraphQL schema from Salesforce org
+npm run graphql:codegen      # Generate TypeScript types from schema
 
 # Testing
-npm run test             # Run Vitest tests
+npm run test                 # Run Vitest tests
 ```
 
 ---
@@ -402,50 +488,76 @@ For detailed component API documentation, see:
 
 ## Version History
 
-### Latest: v1.9.9 (2026-03-29)
-- Fixed routes template importing wrong Home page
-- Now uses installed Home.tsx with component library UI
+### Latest: v1.9.26 (2026-03-29)
+- **Fixed:** AI assistant file truncation (explicit "write complete files" rule)
+- Dashboard validator now requires `.tsx` files (not `.jsx`)
+- Postinstall adds `validate:dashboard` script to package.json
+
+### v1.9.25 (2026-03-29)
+- **Fixed:** Dashboard validator paths (`src/pages/` not `src/components/pages/`)
+- **Fixed:** Validator file extension check (`.tsx` required, `.jsx` is error)
+- Postinstall adds both `reset:command-center` and `validate:dashboard` scripts
 
-### v1.9.8 (2026-03-29)
-- Added complete routes.tsx template with account search & detail
-- Zero-config installation
+### v1.9.24 (2026-03-29)
+- **Fixed:** Home.tsx to render CommandCenter (not search interface)
+- AI rules updated with explicit Step 2.5 for updating Home.tsx
+- Strengthened rule #15 in dashboard feature rules
 
-### v1.9.7 (2026-03-29)
-- Fixed UIButton using non-existent brand colors
-- Changed to standard blue colors
+### v1.9.23 (2026-03-29)
+- **Fixed:** Postinstall now copies `.md` files (skills were being skipped)
+- AI assistant rules now properly installed to project root `.a4drules/`
 
-### v1.9.6 (2026-03-29)
-- Fixed AgentforceConversationClient type definitions
-- Postinstall now skips hidden directories
+### v1.9.22 (2026-03-29)
+- Added automatic `.a4drules` copying to project root for AI assistant discovery
+- Copies `skills/` and `features/` directories during postinstall
 
-### v1.9.5 (2026-03-29)
-- Updated glob dependency to v13.0.6
-- Fixed security vulnerabilities
+### v1.9.21 (2026-03-29)
+- Added automatic dashboard file migration from old location to new location
+- Migrates `src/components/pages/*.jsx` → `src/pages/*.tsx`
+
+### v1.9.20 (2026-03-29)
+- **Fixed:** SKILL.md paths corrected to `src/pages/` (not `src/components/pages/`)
+- All examples updated with correct file locations and imports
+
+### v1.9.19 (2026-03-29)
+- **Fixed:** File extension rule strengthened to MUST be `.tsx` (not "should")
+- Dashboard feature rules updated with no exceptions for `.jsx`
 
 See [CHANGELOG.md](./CHANGELOG.md) for full version history.
 
 ---
 
-## 🤖 AI Agent Skills
+## 🤖 AI Assistant Rules
+
+This package includes comprehensive rules for AI assistants (Agentforce, Claude, etc.) to build dashboards correctly.
+
+During postinstall, rules are copied to your **project root** at `.a4drules/`:
+- **skills/** - Step-by-step implementation guides
+  - `command-center-builder/` - Dashboard building rules
+  - `component-library/` - Component API reference
+  - And more...
+- **features/** - Automatic rules that apply to specific files
+  - `command-center-dashboard-rule.md` - Applies to `src/pages/*.tsx` and `CommandCenter.tsx`
 
-This package includes Claude Code agent skills that teach AI how to work with these components.
+### How AI Assistants Use These Rules
 
-The `.a4drules/` directory contains:
-- **Skills**: Step-by-step guides for building with this library
-- **Features**: Feature-specific implementation rules
-- **Docs**: Data access patterns and UI conventions
+When building dashboards, AI assistants:
+1. **Auto-load feature rules** when editing matching file paths
+2. **Follow explicit steps** from skill guides (create file → wire CommandCenter → update Home)
+3. **Validate** against requirements (`.tsx` only, no hand-rolled HTML, complete files)
+4. **Self-check** with `npm run validate:dashboard` before reporting done
 
-### Using with Claude Code
+### Key Rules AI Assistants Follow
 
-When you install this package, Claude Code automatically discovers the skills and uses them to:
-- Build components correctly
-- Follow your architectural patterns
-- Use the right data access methods
-- Apply consistent styling
+- **File location:** `src/pages/MyDashboard.tsx` (TypeScript required)
+- **File completeness:** Write entire file from imports to closing brace (no truncation)
+- **Components:** Use library components only (no hand-rolled `<div>` cards)
+- **Wiring:** Update CommandCenter.tsx → Home.tsx → routes.tsx
+- **Validation:** Run `npm run validate:dashboard` and fix all errors before done
 
-### Available Skills
+### For Human Developers
 
-Check `.a4drules/skills/` for the full list of included agent skills.
+You can read these same rules at `.a4drules/skills/command-center-builder/SKILL.md` for the complete dashboard building guide.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schandlergarcia/sf-web-components",
-  "version": "1.9.26",
+  "version": "1.9.28",
   "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,6 +32,7 @@
     "src/lib",
     "src/types",
     "README.md",
+    "INSTALL.md",
     ".a4drules"
   ],
   "scripts": {