@schandlergarcia/sf-web-components 1.9.27 → 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/package.json

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