@schandlergarcia/sf-web-components 1.9.9 → 1.9.10

package/README.md

@@ -1,103 +1,416 @@
 # @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
+```
 
-# Build the library
+### Reset Command Center (for enginewebexperience app)
+
+If you're working on the `enginewebexperience` app specifically:
+
+```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
+```
+
+---
+
+## 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'`.
+
+**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 +433,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.10",
   "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
   "type": "module",
   "main": "./dist/index.js",