@schandlergarcia/sf-web-components 1.9.25 → 1.9.27

package/.a4drules/features/command-center-dashboard-rule.md

@@ -13,6 +13,10 @@ These rules are non-negotiable for all dashboard files in `src/pages/` and works
 
 You MUST load the **command-center-builder** and **component-library** skills before writing or editing dashboard pages. These skills contain the full component API reference and builder rules. Do not proceed without them.
 
+## When writing files
+
+**Write COMPLETE files only.** Every file you write must be syntactically valid from the first import to the final closing brace. Do NOT stop writing mid-file, mid-function, or mid-line. Every opened JSX tag must be closed. Every opened string must be closed. Every className attribute must be complete. Incomplete files cause build failures.
+
 ## Critical constraints
 
 1. **File extension MUST be `.tsx`** — This is a TypeScript project. All React components MUST use `.tsx` extension, never `.jsx`. All type definitions are available from the component library.

package/.a4drules/skills/command-center-builder/SKILL.md

@@ -15,7 +15,7 @@ These rules apply when building dashboards rendered by `CommandCenter.tsx`. For
 
 **Every time you build a dashboard, you MUST follow these non-negotiable rules. Violations are the #1 cause of rejected dashboards.**
 
-1. **Actually write files to disk.** Use the file-writing tools to create `.tsx` files (NOT `.jsx`) in `src/pages/` and update `CommandCenter.tsx` to import your dashboard. This is a TypeScript project - all React components MUST use `.tsx` extension. If you only describe what you would build without creating the files, the dashboard will not render. Verify the files exist after writing them.
+1. **Actually write COMPLETE files to disk.** Use the file-writing tools to create `.tsx` files (NOT `.jsx`) in `src/pages/` and update `CommandCenter.tsx` to import your dashboard. This is a TypeScript project - all React components MUST use `.tsx` extension. **CRITICAL: Write the ENTIRE file from import statements through the closing brace `}` of the export statement. Do NOT stop mid-file, mid-function, or mid-line. Every JSX tag you open must be closed. Every string you open must be closed. Every className attribute must be complete.** If you only describe what you would build without creating the files, the dashboard will not render. Verify the files exist after writing them.
 
 2. **Use ONLY library components** from `@/components/library` for all cards, charts, tables, lists, and feeds. The library has 30+ components — there is no reason to hand-roll HTML. See the component table below.
 

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.25",
+  "version": "1.9.27",
   "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
   "type": "module",
   "main": "./dist/index.js",