@schandlergarcia/sf-web-components 1.9.28 → 1.9.30

package/README.md

@@ -1,573 +1,146 @@
 # @schandlergarcia/sf-web-components
 
-Comprehensive React component library for Salesforce web applications with 100+ TypeScript components, built on Tailwind CSS v4 and shadcn/ui.
-
-## 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
-
----
+Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui components.
 
 ## 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
-# 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
+npm install @schandlergarcia/sf-web-components
 ```
 
-### 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)
-
-✅ **Installs complete routes configuration** at `src/routes.tsx`
-- `/` (Home) - Renders CommandCenter (dashboard wrapper)
-- `/accounts` - Account search with filters and sorting
-- `/accounts/:recordId` - Account detail page
-- `*` (NotFound) - 404 error page
-
-✅ **Installs 4 page templates** to `src/pages/`
-- `Home.tsx` - Renders CommandCenter (dashboard wrapper)
-- `NotFound.tsx` - 404 error page
-- `Search.tsx` - Generic search page
-- `BlankDashboard.tsx` - Empty dashboard template
+## Peer Dependencies
 
-✅ **Copies type definitions** to `src/types/`
-- `conversation.ts` - Types for AgentforceConversationClient
+This package requires:
+- React 18+ or 19+
+- Tailwind CSS v4
+- @tailwindcss/vite
 
-✅ **Copies utility files** to `src/lib/`
-- `utils.ts` - Helper functions (cn, etc.)
-
-✅ **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
+## Usage
 
-# 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
-
-### Quick Start - Building a Dashboard
+### Import Components
 
 ```tsx
-import { MetricCard, ChartCard, TableCard } from '@/components/library';
-import { PageContainer } from '@/components/library/layout/PageContainer';
+import { Button, Card } from '@schandlergarcia/sf-web-components';
+import { cn } from '@schandlergarcia/sf-web-components/lib';
 
-export default function Dashboard() {
+function App() {
   return (
-    <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>
+    <Card className={cn('p-4')}>
+      <Button>Click me</Button>
+    </Card>
   );
 }
 ```
 
-### Available Components
-
-#### UI Components (`@/components/library/ui/`)
-```tsx
-import { UIButton, UIInput, Card, Alert, EmptyState, Checkbox, Label } from '@/components/library';
-
-<UIButton variant="primary">Click Me</UIButton>
-<UIInput placeholder="Search..." />
-<Alert variant="success">Success message</Alert>
-```
-
-#### 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} />
-```
-
-#### Charts (`@/components/library/charts/`)
-```tsx
-import { D3Chart, D3ChartTemplates } from '@/components/library';
-
-<D3Chart
-  data={data}
-  width={600}
-  height={400}
-  chartType="bar"
-  xKey="month"
-  yKey="revenue"
-/>
-```
-
-#### Filters (`@/components/library/filters/`)
-```tsx
-import { SearchFilter, SelectFilter, DateRangeFilter, FilterBar } from '@/components/library';
+### Import Styles
 
-<FilterBar>
-  <SearchFilter field="name" placeholder="Search accounts..." />
-  <SelectFilter field="industry" options={industries} />
-  <DateRangeFilter field="createdDate" />
-</FilterBar>
-```
+Add to your main CSS file:
 
-#### Forms (`@/components/library/forms/`)
-```tsx
-import { FormRenderer, FormField, FormModal } from '@/components/library';
-
-<FormRenderer
-  fields={fields}
-  values={values}
-  onChange={handleChange}
-  onSubmit={handleSubmit}
-/>
+```css
+@import '@schandlergarcia/sf-web-components/styles';
 ```
 
-### Common Patterns
-
-#### 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';
+### Tailwind Configuration
 
-export default function FilteredDashboard() {
-  const [filters, setFilters] = useState({});
+Extend your `tailwind.config.ts`:
 
-  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>
-  );
-}
-```
+```ts
+import type { Config } from 'tailwindcss';
 
-#### Data Table with Actions
-```tsx
-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>
+export default {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@schandlergarcia/sf-web-components/dist/**/*.{js,jsx}'
+  ],
+  theme: {
+    extend: {}
   }
-];
-
-<TableCard title="Accounts" columns={columns} data={accounts} />
+} satisfies Config;
 ```
 
----
+## Components
 
-## Resetting Your App
+This library includes:
+- UI components (Button, Card, Input, etc.)
+- Data components (Tables, Lists)
+- Chart components (via Recharts)
+- Form components
+- Filter components
+- Layout components
 
-If you need to remove the component library and start fresh:
+## Utilities
 
-### Option 1: Remove Components Only
+```tsx
+import { cn } from '@schandlergarcia/sf-web-components/lib';
 
-```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
+// Merge Tailwind classes with conflict resolution
+const className = cn('px-2 py-1', 'px-4'); // Result: 'py-1 px-4'
 ```
 
-### Option 2: Full Reset
+## Development
 
 ```bash
-# 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
+# Install dependencies
 npm install
-npm run build
-```
-
-### Reset Command Center
 
-This script resets any app back to the blank dashboard baseline state:
-
-```bash
-# Reset 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 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
-
-**Exit codes:** 0 = pass, 1 = errors found (must fix before dashboard is complete)
-
----
-
-## Troubleshooting
-
-### Postinstall didn't run automatically
-
-**Problem:** After `npm install`, component library isn't copied and routes aren't updated.
+# Build the library
+npm run build
 
-**Solution:** Run postinstall manually:
-```bash
-node node_modules/@schandlergarcia/sf-web-components/scripts/postinstall.mjs
+# Build types only
+npm run build:types
 ```
 
-### Build errors about missing D3 types
+## Publishing
 
-**Problem:** TypeScript errors about `module 'd3'` or `module 'topojson-client'`.
+This package publishes to the **public npm registry** at https://registry.npmjs.org.
 
-**Solution:** Install type definitions:
-```bash
-npm install --save-dev @types/d3 @types/topojson-client
-```
-
-### Buttons appear blank/invisible
+### Prerequisites
+- Be logged in to npm: `npm login`
+- Have publish permissions for the `@schandlergarcia` scope
 
-**Problem:** UIButton text is invisible (white text on transparent background).
+### Publish a New Version
 
-**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
+# Bump version (patch, minor, or major)
+npm version patch  # 1.9.29 → 1.9.30
+npm version minor  # 1.9.29 → 1.10.0
+npm version major  # 1.9.29 → 2.0.0
 
-**Problem:** Home page shows the scaffolded UI instead of component library UI.
+# Or manually edit package.json version field
 
-**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
+# Build and publish
 npm run build
+npm publish
 ```
 
-### 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
-```
-
-### 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:
-
+The package is published as **public** and can be installed by anyone:
 ```bash
-# Development
-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
-
-# Testing
-npm run test                 # Run Vitest tests
+npm install @schandlergarcia/sf-web-components
 ```
 
----
-
-## 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.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.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.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.22 (2026-03-29)
-- Added automatic `.a4drules` copying to project root for AI assistant discovery
-- Copies `skills/` and `features/` directories during postinstall
-
-### 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 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`
-
-### How AI Assistants Use These Rules
-
-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
 
-### Key Rules AI Assistants Follow
+## 🤖 AI Agent Skills
 
-- **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
+This package includes Claude Code agent skills that teach AI how to work with these components.
 
-### For Human Developers
+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
 
-You can read these same rules at `.a4drules/skills/command-center-builder/SKILL.md` for the complete dashboard building guide.
+### Using with Claude Code
 
----
+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
 
-## Support
+### Available Skills
 
-- **Issues:** [GitHub Issues](https://github.com/schandlergarcia/sf-web-components/issues)
-- **Package:** [npm](https://www.npmjs.com/package/@schandlergarcia/sf-web-components)
+Check `.a4drules/skills/` for the full list of included agent skills.
 
----
 
 ## License
 
-MIT License - See LICENSE.txt for details
+MIT

package/dist/components/library/cards/ActionList.d.ts

@@ -1,11 +1,11 @@
-export interface Action {
+/**
+ * Row of action buttons — typically used at the bottom of a dashboard section.
+ *
+ * @param {{ label: string, [key]: any }[] | string[]} actions
+ * @param {string}     title
+ * @param {Function}   onAction  Called with the action object/string when clicked
+ */
+export default function ActionList({ actions, title, onAction, className, }: {
     label: string;
-    [key: string]: unknown;
-}
-export interface ActionListProps {
-    actions?: (Action | string)[];
-    title?: string;
-    onAction?: (action: Action | string) => void;
-    className?: string;
-}
-export default function ActionList({ actions, title, onAction, className, }: ActionListProps): import("react/jsx-runtime").JSX.Element;
+    [key]: any;
+}[] | string[]): import("react/jsx-runtime").JSX.Element;

package/dist/components/library/cards/ActionList.js

@@ -1,6 +1,7 @@
 import { jsxs as i, jsx as r } from "react/jsx-runtime";
-import m from "../ui/UIButton.js";
-function p({
+import "react";
+import m from "../ui/Button.js";
+function x({
   actions: s = [],
   title: t,
   onAction: l,
@@ -21,6 +22,6 @@ function p({
   ] });
 }
 export {
-  p as default
+  x as default
 };
 //# sourceMappingURL=ActionList.js.map