@schandlergarcia/sf-web-components 1.9.9 → 1.9.11

package/README.md

@@ -1,103 +1,424 @@
 # @schandlergarcia/sf-web-components
 
-Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui components.
+Comprehensive React component library for Salesforce web applications with 100+ TypeScript components, built on Tailwind CSS v4 and shadcn/ui.
 
-**🎯 TypeScript Migration in Progress** (v1.4.0): Core UI components now have full TypeScript support with exported prop interfaces. See `docs/TYPESCRIPT_MIGRATION.md` for status and contribution guide.
+## Features
+
+- ✅ **102+ TypeScript Components** - Cards, charts, forms, filters, chat UI, and more
+- ✅ **Zero-Config Installation** - Postinstall script handles everything automatically
+- ✅ **Complete Dashboard Framework** - Pre-built layouts, metric cards, and data visualization
+- ✅ **Account Search & Detail** - Full example pages with filtering, sorting, and pagination
+- ✅ **Tailwind CSS v4** - Modern styling with dark mode support
+- ✅ **Type-Safe** - Full TypeScript support with exported interfaces
+
+---
 
 ## Installation
 
+### Prerequisites
+
+- Salesforce web application generated with `sf webapp generate --template react-ts`
+- Node.js 18+ and npm
+- Tailwind CSS v4 configured in your project
+
+### Steps
+
 ```bash
-npm install @schandlergarcia/sf-web-components
+# 1. Navigate to your web application directory
+cd force-app/main/default/webapplications/YOUR_APP_NAME
+
+# 2. Install the component library
+npm install @schandlergarcia/sf-web-components@latest
+
+# 3. Run postinstall script (npm sometimes skips automatic postinstall)
+node node_modules/@schandlergarcia/sf-web-components/scripts/postinstall.mjs
+
+# 4. Install required type definitions for D3 charts
+npm install --save-dev @types/d3 @types/topojson-client
+
+# 5. Build to verify installation
+npm run build
+
+# 6. Start development server
+npm run dev
 ```
 
-## Peer Dependencies
+### What Gets Installed
+
+The postinstall script automatically:
+
+✅ **Copies 102 component files** to `src/components/library/`
+- UI components (buttons, inputs, cards, alerts)
+- HeroUI wrappers (modals, dropdowns, tabs)
+- Charts (D3 visualizations, bar/line charts, geo maps)
+- Cards (metric cards, chart cards, table cards, status cards)
+- Forms (form renderer, form fields, validation)
+- Filters (search, date range, multi-select, numeric range)
+- Chat components (message UI, typing indicators, suggestions)
 
-This package requires:
-- React 18+ or 19+
-- Tailwind CSS v4
-- @tailwindcss/vite
+✅ **Installs complete routes configuration** at `src/routes.tsx`
+- Home page with account search
+- `/accounts` - Account search with filters and sorting
+- `/accounts/:recordId` - Account detail page
+- NotFound page
 
-## Usage
+✅ **Installs 4 page templates** to `src/pages/`
+- `Home.tsx` - Search interface with UIButton and UIInput
+- `NotFound.tsx` - 404 error page
+- `Search.tsx` - Generic search page
+- `BlankDashboard.tsx` - Empty dashboard template
 
-### Import Components
+✅ **Copies type definitions** to `src/types/`
+- `conversation.ts` - Types for AgentforceConversationClient
+
+✅ **Copies utility files** to `src/lib/`
+- `utils.ts` - Helper functions (cn, etc.)
+
+---
+
+## Using the Dashboard Framework
+
+### Quick Start - Building a Dashboard
 
 ```tsx
-import { Button, Card } from '@schandlergarcia/sf-web-components';
-import { cn } from '@schandlergarcia/sf-web-components/lib';
+import { MetricCard, ChartCard, TableCard } from '@/components/library';
+import { PageContainer } from '@/components/library/layout/PageContainer';
 
-function App() {
+export default function Dashboard() {
   return (
-    <Card className={cn('p-4')}>
-      <Button>Click me</Button>
-    </Card>
+    <PageContainer>
+      {/* Metrics Row */}
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-6 mb-6">
+        <MetricCard
+          title="Total Revenue"
+          value="$1.2M"
+          change="+12.5%"
+          changeType="positive"
+        />
+        <MetricCard
+          title="Active Users"
+          value={1284}
+          change="+8.2%"
+          changeType="positive"
+        />
+        <MetricCard
+          title="Conversion Rate"
+          value="3.2%"
+          change="-0.5%"
+          changeType="negative"
+        />
+      </div>
+
+      {/* Charts Row */}
+      <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+        <ChartCard
+          title="Revenue Trend"
+          description="Last 6 months"
+          chartType="line"
+          data={revenueData}
+        />
+        <TableCard
+          title="Top Accounts"
+          columns={columns}
+          data={accountsData}
+        />
+      </div>
+    </PageContainer>
   );
 }
 ```
 
-### Import Styles
+### Available Components
 
-Add to your main CSS file:
+#### UI Components (`@/components/library/ui/`)
+```tsx
+import { UIButton, UIInput, Card, Alert, EmptyState, Checkbox, Label } from '@/components/library';
 
-```css
-@import '@schandlergarcia/sf-web-components/styles';
+<UIButton variant="primary">Click Me</UIButton>
+<UIInput placeholder="Search..." />
+<Alert variant="success">Success message</Alert>
 ```
 
-### Tailwind Configuration
+#### Cards (`@/components/library/cards/`)
+```tsx
+import { MetricCard, ChartCard, TableCard, StatusCard, ListCard } from '@/components/library';
+
+<MetricCard title="Revenue" value="$1.2M" change="+12%" changeType="positive" />
+<ChartCard title="Sales" chartType="bar" data={data} />
+<TableCard title="Accounts" columns={cols} data={rows} />
+```
 
-Extend your `tailwind.config.ts`:
+#### Charts (`@/components/library/charts/`)
+```tsx
+import { D3Chart, D3ChartTemplates } from '@/components/library';
+
+<D3Chart
+  data={data}
+  width={600}
+  height={400}
+  chartType="bar"
+  xKey="month"
+  yKey="revenue"
+/>
+```
 
-```ts
-import type { Config } from 'tailwindcss';
+#### Filters (`@/components/library/filters/`)
+```tsx
+import { SearchFilter, SelectFilter, DateRangeFilter, FilterBar } from '@/components/library';
 
-export default {
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@schandlergarcia/sf-web-components/dist/**/*.{js,jsx}'
-  ],
-  theme: {
-    extend: {}
-  }
-} satisfies Config;
+<FilterBar>
+  <SearchFilter field="name" placeholder="Search accounts..." />
+  <SelectFilter field="industry" options={industries} />
+  <DateRangeFilter field="createdDate" />
+</FilterBar>
 ```
 
-## Components
+#### Forms (`@/components/library/forms/`)
+```tsx
+import { FormRenderer, FormField, FormModal } from '@/components/library';
+
+<FormRenderer
+  fields={fields}
+  values={values}
+  onChange={handleChange}
+  onSubmit={handleSubmit}
+/>
+```
+
+### Common Patterns
 
-This library includes:
-- UI components (Button, Card, Input, etc.)
-- Data components (Tables, Lists)
-- Chart components (via Recharts)
-- Form components
-- Filter components
-- Layout components
+#### Dashboard with Filters
+```tsx
+import { PageContainer } from '@/components/library/layout/PageContainer';
+import { MetricCard } from '@/components/library/cards/MetricCard';
+import { FilterBar, SearchFilter, SelectFilter } from '@/components/library/filters';
+
+export default function FilteredDashboard() {
+  const [filters, setFilters] = useState({});
 
-## Utilities
+  return (
+    <PageContainer>
+      <FilterBar>
+        <SearchFilter field="search" onChange={setFilters} />
+        <SelectFilter field="status" options={statusOptions} onChange={setFilters} />
+      </FilterBar>
+
+      <div className="grid grid-cols-3 gap-6">
+        <MetricCard title="Total" value={data.total} />
+        <MetricCard title="Active" value={data.active} />
+        <MetricCard title="Pending" value={data.pending} />
+      </div>
+    </PageContainer>
+  );
+}
+```
 
+#### Data Table with Actions
 ```tsx
-import { cn } from '@schandlergarcia/sf-web-components/lib';
+import { TableCard } from '@/components/library/cards/TableCard';
+import { UIButton } from '@/components/library/ui/UIButton';
+
+const columns = [
+  { key: 'name', label: 'Name' },
+  { key: 'status', label: 'Status' },
+  {
+    key: 'actions',
+    label: 'Actions',
+    render: (row) => <UIButton onClick={() => handleEdit(row)}>Edit</UIButton>
+  }
+];
+
+<TableCard title="Accounts" columns={columns} data={accounts} />
+```
 
-// Merge Tailwind classes with conflict resolution
-const className = cn('px-2 py-1', 'px-4'); // Result: 'py-1 px-4'
+---
+
+## Resetting Your App
+
+If you need to remove the component library and start fresh:
+
+### Option 1: Remove Components Only
+
+```bash
+# Run the removal script
+node node_modules/@schandlergarcia/sf-web-components/scripts/remove-local-components.mjs
+
+# This removes:
+# - src/components/library/
+# - src/pages/Home.tsx, Search.tsx, BlankDashboard.tsx (keeps NotFound.tsx)
+# - src/types/conversation.ts
+# - Reverts routes.tsx to minimal default
 ```
 
-## Development
+### Option 2: Full Reset
 
 ```bash
-# Install dependencies
+# 1. Uninstall the package
+npm uninstall @schandlergarcia/sf-web-components
+
+# 2. Manually delete installed files
+rm -rf src/components/library
+rm -rf src/types/conversation.ts
+rm src/pages/Home.tsx src/pages/Search.tsx src/pages/BlankDashboard.tsx
+
+# 3. Restore default routes.tsx
+cat > src/routes.tsx << 'EOF'
+import type { RouteObject } from 'react-router';
+import AppLayout from './appLayout';
+import NotFound from './pages/NotFound';
+
+export const routes: RouteObject[] = [
+  {
+    path: "/",
+    element: <AppLayout />,
+    children: [
+      {
+        path: '*',
+        element: <NotFound />
+      }
+    ]
+  }
+];
+EOF
+
+# 4. Clean install
 npm install
+npm run build
+```
+
+### Reset Command Center (All Apps)
+
+This script resets any app back to the blank dashboard baseline state:
+
+```bash
+# This script resets the command center to the blank dashboard template
+npm run reset:command-center
+
+# Or run directly:
+bash node_modules/@schandlergarcia/sf-web-components/scripts/reset-command-center.sh
+```
+
+**What it does:**
+- Removes custom dashboard pages
+- Restalls BlankDashboard.tsx with EmptyState
+- Resets CommandCenter.tsx (preserves theme mode)
+- Updates Home.tsx to search interface
+- Resets routes to baseline configuration
+- Preserves: component library, authentication, all dependencies
+
+---
+
+## Troubleshooting
+
+### Postinstall didn't run automatically
+
+**Problem:** After `npm install`, component library isn't copied and routes aren't updated.
+
+**Solution:** Run postinstall manually:
+```bash
+node node_modules/@schandlergarcia/sf-web-components/scripts/postinstall.mjs
+```
+
+### Build errors about missing D3 types
+
+**Problem:** TypeScript errors about `module 'd3'` or `module 'topojson-client'`.
 
-# Build the library
+**Solution:** Install type definitions:
+```bash
+npm install --save-dev @types/d3 @types/topojson-client
+```
+
+### Buttons appear blank/invisible
+
+**Problem:** UIButton text is invisible (white text on transparent background).
+
+**Solution:** This was fixed in v1.9.7+. Update to the latest version:
+```bash
+npm install @schandlergarcia/sf-web-components@latest
+node node_modules/@schandlergarcia/sf-web-components/scripts/postinstall.mjs
+```
+
+### "Old UI" still showing after install
+
+**Problem:** Home page shows the scaffolded UI instead of component library UI.
+
+**Solution:** Fixed in v1.9.9+. Update and re-run postinstall:
+```bash
+npm install @schandlergarcia/sf-web-components@latest
+node node_modules/@schandlergarcia/sf-web-components/scripts/postinstall.mjs
 npm run build
+```
 
-# Build types only
-npm run build:types
+### Account detail pages show 404
+
+**Problem:** Clicking on an account in search results shows 404.
+
+**Solution:** Routes template includes account detail route. Re-run postinstall:
+```bash
+node node_modules/@schandlergarcia/sf-web-components/scripts/postinstall.mjs
 ```
 
-## Publishing
+### ESLint errors about `.sfdx` directory
+
+**Problem:** ESLint errors about files in `src/components/library/.sfdx/`.
+
+**Solution:** Fixed in v1.9.6+. The postinstall script now skips hidden directories.
+
+---
+
+## Package Scripts
+
+Available npm scripts in the consuming application:
 
 ```bash
-npm publish
+# Development
+npm run dev              # Start Vite dev server
+npm run build            # TypeScript check + Vite build
+npm run lint             # Run ESLint
+
+# GraphQL (if using)
+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
 ```
 
+---
+
+## Component Documentation
+
+For detailed component API documentation, see:
+- [Component Library Reference](https://github.com/schandlergarcia/sf-web-components/blob/main/COMPONENTS.md)
+- [TypeScript Migration Guide](https://github.com/schandlergarcia/sf-web-components/blob/main/docs/TYPESCRIPT_MIGRATION.md)
+
+---
+
+## 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
+
+### v1.9.8 (2026-03-29)
+- Added complete routes.tsx template with account search & detail
+- Zero-config installation
+
+### v1.9.7 (2026-03-29)
+- Fixed UIButton using non-existent brand colors
+- Changed to standard blue colors
+
+### v1.9.6 (2026-03-29)
+- Fixed AgentforceConversationClient type definitions
+- Postinstall now skips hidden directories
+
+### v1.9.5 (2026-03-29)
+- Updated glob dependency to v13.0.6
+- Fixed security vulnerabilities
+
+See [CHANGELOG.md](./CHANGELOG.md) for full version history.
+
+---
 
 ## 🤖 AI Agent Skills
 
@@ -120,7 +441,15 @@ When you install this package, Claude Code automatically discovers the skills an
 
 Check `.a4drules/skills/` for the full list of included agent skills.
 
+---
+
+## Support
+
+- **Issues:** [GitHub Issues](https://github.com/schandlergarcia/sf-web-components/issues)
+- **Package:** [npm](https://www.npmjs.com/package/@schandlergarcia/sf-web-components)
+
+---
 
 ## License
 
-MIT
+MIT License - See LICENSE.txt for details

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schandlergarcia/sf-web-components",
-  "version": "1.9.9",
+  "version": "1.9.11",
   "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
   "type": "module",
   "main": "./dist/index.js",

package/scripts/postinstall.mjs

@@ -105,6 +105,35 @@ if (fs.existsSync(sourceWorkspaceDir)) {
   console.log(`  ✓ Copied ${workspaceFilesCopied} workspace files\n`);
 }
 
+// Copy workspace templates (CommandCenter, etc.)
+const workspaceTemplatesDir = path.join(packageRoot, 'src/templates/workspace');
+if (fs.existsSync(workspaceTemplatesDir)) {
+  if (!fs.existsSync(targetWorkspaceDir)) {
+    fs.mkdirSync(targetWorkspaceDir, { recursive: true });
+  }
+
+  const workspaceTemplates = fs.readdirSync(workspaceTemplatesDir).filter(f => f.endsWith('.template'));
+  let workspaceTemplatesCopied = 0;
+
+  for (const template of workspaceTemplates) {
+    const sourcePath = path.join(workspaceTemplatesDir, template);
+    const targetFileName = template.replace('.template', '');
+    const targetPath = path.join(targetWorkspaceDir, targetFileName);
+
+    try {
+      const content = fs.readFileSync(sourcePath, 'utf-8');
+      fs.writeFileSync(targetPath, content, 'utf-8');
+      workspaceTemplatesCopied++;
+    } catch (error) {
+      console.error(`  ✗ Failed to copy ${targetFileName}: ${error.message}`);
+    }
+  }
+
+  if (workspaceTemplatesCopied > 0) {
+    console.log(`  ✓ Copied ${workspaceTemplatesCopied} workspace template files\n`);
+  }
+}
+
 // Copy pages directory (sample pages, etc.)
 const sourcePagesDir = path.join(packageRoot, 'src/components/pages');
 const targetComponentPagesDir = path.join(cwd, 'src/components/pages');
@@ -218,4 +247,5 @@ console.log('\n📊 Summary:');
 console.log(`  - Copied ${componentsCopied} UI components`);
 console.log(`  - Updated ${filesUpdated} files`);
 console.log(`  - Installed ${templatesInstalled} page templates`);
+console.log(`  - Installed CommandCenter.tsx for dashboard management`);
 console.log('\n✅ Setup complete! UI components are now local for optimal Tailwind scanning\n');

package/scripts/reset-command-center.sh

@@ -37,8 +37,9 @@ echo ""
 echo "→ Removing custom dashboards…"
 
 removed=0
-for f in src/components/pages/*Dashboard*.jsx src/components/pages/*Dashboard*.tsx; do
-  if [ -f "$f" ]; then
+for f in src/pages/*Dashboard*.tsx src/pages/*Dashboard*.jsx; do
+  # Don't remove BlankDashboard
+  if [ -f "$f" ] && [[ "$(basename "$f")" != "BlankDashboard"* ]]; then
     rm "$f"
     echo "  ✓ Removed $(basename "$f")"
     removed=$((removed + 1))
@@ -52,11 +53,10 @@ echo ""
 
 # ── 2. Write the blank starter dashboard ────────────────────────────────────
 
-BLANK="src/components/pages/BlankDashboard.jsx"
+BLANK="src/pages/BlankDashboard.tsx"
 echo "→ Creating ${BLANK}..."
 
 cat > "$BLANK" << 'DASHBOARD_EOF'
-import React from "react";
 import { RocketLaunchIcon } from "@heroicons/react/24/outline";
 import { EmptyState } from "@/components/library";
 
@@ -80,9 +80,12 @@ echo ""
 # ── 3. Update CommandCenter.tsx to use BlankDashboard ────────────────────────
 #    Preserves theme initialMode if previously customized.
 
-WRAPPER="src/components/pages/CommandCenter.tsx"
+WRAPPER="src/components/workspace/CommandCenter.tsx"
 echo "→ Updating ${WRAPPER}..."
 
+# Create workspace directory if it doesn't exist
+mkdir -p "src/components/workspace"
+
 # Extract existing initialMode from AppThemeProvider (default: "light")
 THEME_MODE="light"
 if [ -f "$WRAPPER" ]; then
@@ -96,19 +99,17 @@ fi
 cat > "$WRAPPER" << WRAPPER_EOF
 import AppThemeProvider from "@/components/library/theme/AppThemeProvider";
 import DataModeProvider from "@/components/library/data/DataModeProvider";
-import { Toast } from "@heroui/react";
-import BlankDashboard from "./BlankDashboard";
+import { Toaster } from "sonner";
+import BlankDashboard from "../../pages/BlankDashboard";
 
 export default function CommandCenter() {
   return (
-    <div className="heroui-scope">
-      <AppThemeProvider initialMode="${THEME_MODE}">
-        <DataModeProvider initialMode="sample">
-          <BlankDashboard />
-          <Toast.Provider placement="bottom end" />
-        </DataModeProvider>
-      </AppThemeProvider>
-    </div>
+    <AppThemeProvider initialMode="${THEME_MODE}">
+      <DataModeProvider initialMode="sample">
+        <BlankDashboard />
+        <Toaster position="bottom-right" />
+      </DataModeProvider>
+    </AppThemeProvider>
   );
 }
 WRAPPER_EOF

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>
+  );
+}