@schandlergarcia/sf-web-components 1.9.41 → 1.9.42

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.41",
+  "version": "1.9.42",
   "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,10 +28,12 @@
     "dist",
     "scripts",
     "data",
+    "src/templates",
     "src/components",
     "src/lib",
     "src/types",
     "README.md",
+    "INSTALL.md",
     ".a4drules"
   ],
   "scripts": {

package/src/templates/config/routes.tsx.template

@@ -0,0 +1,33 @@
+import type { RouteObject } from 'react-router';
+import AppLayout from './appLayout';
+import Home from './pages/Home';
+import AccountSearch from './features/object-search/__examples__/pages/AccountSearch';
+import AccountObjectDetailPage from './features/object-search/__examples__/pages/AccountObjectDetailPage';
+import NotFound from './pages/NotFound';
+
+export const routes: RouteObject[] = [
+  {
+    path: "/",
+    element: <AppLayout />,
+    children: [
+      {
+        index: true,
+        element: <Home />,
+        handle: { showInNavigation: true, label: "Home" }
+      },
+      {
+        path: 'accounts',
+        element: <AccountSearch />,
+        handle: { showInNavigation: true, label: "Accounts" }
+      },
+      {
+        path: 'accounts/:recordId',
+        element: <AccountObjectDetailPage />
+      },
+      {
+        path: '*',
+        element: <NotFound />
+      }
+    ]
+  }
+];

package/src/templates/pages/BlankDashboard.tsx.template

@@ -0,0 +1,15 @@
+import { RocketLaunchIcon } from "@heroicons/react/24/outline";
+import { EmptyState } from "@/components/library";
+
+export default function BlankDashboard() {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-slate-50 dark:bg-slate-950 transition-colors">
+      <EmptyState
+        size="lg"
+        icon={<RocketLaunchIcon className="h-14 w-14" />}
+        heading="Bespoke App Template"
+        body="Component library loaded and ready to go."
+      />
+    </div>
+  );
+}

package/src/templates/pages/Home.tsx.template

@@ -0,0 +1,58 @@
+import { useState } from "react";
+import { useNavigate } from "react-router";
+import UIInput from '@/components/library/ui/UIInput';
+import UIButton from '@/components/library/ui/UIButton';
+import { Search } from "lucide-react";
+
+export default function HomePage() {
+	const [searchQuery, setSearchQuery] = useState("");
+	const navigate = useNavigate();
+
+	const handleSearch = () => {
+		const trimmed = searchQuery.trim();
+		if (trimmed) {
+			navigate(`/accounts?search=${encodeURIComponent(trimmed)}`);
+		} else {
+			navigate('/accounts');
+		}
+	};
+
+	const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+		if (e.key === "Enter") {
+			e.preventDefault();
+			handleSearch();
+		}
+	};
+
+	return (
+		<div className="flex min-h-[80vh] items-center justify-center px-4 sm:px-6 lg:px-8 bg-slate-50 dark:bg-slate-950 transition-colors">
+			<div className="w-full max-w-4xl">
+				<div className="text-center mb-8">
+					<h1 className="text-4xl font-bold text-slate-900 dark:text-slate-50 mb-4">Search</h1>
+					<p className="text-lg text-slate-600 dark:text-slate-300">Find records across your organization.</p>
+				</div>
+				<div className="flex flex-col gap-4">
+					<div className="relative">
+						<Search className="absolute left-3 top-1/2 -translate-y-1/2 h-5 w-5 text-slate-400" />
+						<UIInput
+							type="text"
+							value={searchQuery}
+							onChange={(e) => setSearchQuery(e.target.value)}
+							onKeyDown={handleKeyDown}
+							placeholder="Search..."
+							className="pl-10 w-full"
+						/>
+					</div>
+					<div className="flex gap-3 justify-center">
+						<UIButton onClick={handleSearch} variant="primary">
+							Search
+						</UIButton>
+						<UIButton onClick={() => navigate('/accounts')} variant="secondary">
+							Browse All
+						</UIButton>
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+}

package/src/templates/pages/NotFound.tsx.template

@@ -0,0 +1,19 @@
+import { useNavigate } from "react-router";
+import UIButton from '@/components/library/ui/UIButton';
+
+export default function NotFound() {
+	const navigate = useNavigate();
+
+	return (
+		<div className="flex min-h-[80vh] items-center justify-center px-4 sm:px-6 lg:px-8">
+			<div className="w-full max-w-2xl text-center">
+				<h1 className="text-6xl font-bold text-slate-900 dark:text-slate-50 mb-4">404</h1>
+				<h2 className="text-2xl font-semibold text-slate-700 dark:text-slate-300 mb-4">Page Not Found</h2>
+				<p className="text-lg text-slate-600 dark:text-slate-400 mb-8">
+					The page you're looking for doesn't exist.
+				</p>
+				<UIButton onClick={() => navigate("/")}>Go Home</UIButton>
+			</div>
+		</div>
+	);
+}

package/src/templates/pages/Search.tsx.template

@@ -0,0 +1,13 @@
+export default function Search() {
+	return (
+		<div className="flex min-h-[80vh] items-center justify-center px-4 sm:px-6 lg:px-8 bg-slate-50 dark:bg-slate-950 transition-colors">
+			<div className="w-full max-w-4xl">
+				<div className="text-center mb-8">
+					<h1 className="text-4xl font-bold text-slate-900 dark:text-slate-50 mb-4">Search</h1>
+					<p className="text-lg text-slate-600 dark:text-slate-300">Find records across your organization.</p>
+				</div>
+				<p className="text-center text-slate-500 dark:text-slate-400">Search functionality coming soon...</p>
+			</div>
+		</div>
+	);
+}

package/src/templates/workspace/CommandCenter.tsx.template

@@ -0,0 +1,15 @@
+import AppThemeProvider from "@/components/library/theme/AppThemeProvider";
+import DataModeProvider from "@/components/library/data/DataModeProvider";
+import { Toaster } from "sonner";
+import BlankDashboard from "../pages/BlankDashboard";
+
+export default function CommandCenter() {
+  return (
+    <AppThemeProvider initialMode="light">
+      <DataModeProvider initialMode="sample">
+        <BlankDashboard />
+        <Toaster position="bottom-right" />
+      </DataModeProvider>
+    </AppThemeProvider>
+  );
+}

package/src/types/conversation.ts

@@ -0,0 +1,48 @@
+/**
+ * Type definitions for Agentforce Conversation Client
+ */
+
+export interface ResolvedEmbedOptions {
+  salesforceOrigin?: string;
+  frontdoorUrl?: string;
+}
+
+export interface RenderingConfig {
+  mode?: 'inline' | 'modal' | 'sidebar' | 'floating';
+  theme?: 'light' | 'dark' | 'auto';
+  width?: string | number;
+  height?: string | number;
+  headerEnabled?: boolean;
+}
+
+export interface AgentforceClientConfig {
+  agentId?: string;
+  devName?: string;
+  renderingConfig?: RenderingConfig;
+  locale?: string;
+  styleTokens?: Record<string, string>;
+  [key: string]: any;
+}
+
+/**
+ * Props interface for AgentforceConversationClient component.
+ * Uses flat props that get normalized to AgentforceClientConfig internally.
+ */
+export interface AgentforceConversationClientProps {
+  /** Agent ID to load */
+  agentId?: string;
+  /** Whether to render inline (true) or floating (false) */
+  inline?: boolean;
+  /** Whether to show the header in the conversation UI */
+  headerEnabled?: boolean;
+  /** Width of the conversation UI */
+  width?: string | number;
+  /** Height of the conversation UI */
+  height?: string | number;
+  /** Custom style tokens for theming */
+  styleTokens?: Record<string, string>;
+  /** Salesforce origin URL */
+  salesforceOrigin?: string;
+  /** Frontdoor URL for authentication */
+  frontdoorUrl?: string;
+}