npm package: @schandlergarcia/sf-web-components
Description: Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui
Latest version: 2.2.1

# @schandlergarcia/sf-web-components

Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui components.

## Installation

```bash
npm install @schandlergarcia/sf-web-components
```

## Peer Dependencies

This package requires:
- React 18+ or 19+
- Tailwind CSS v4
- @tailwindcss/vite

## Usage

### Import Components

```tsx
// Library components (for command centers/dashboards)
import { UIButton, MetricCard } from '@/components/library';
import { cn } from '@/lib/utils';

function Dashboard() {
  return (
    <MetricCard
      title="Total Sales"
      value="$1.2M"
      trend={{ value: 12, direction: 'up' }}
      footer={<UIButton variant="primary">View Details</UIButton>}
    />
  );
}
```

**Note:** After installation, components are copied to `src/components/library/` for Tailwind scanning.
Import from `@/components/library` (not from the package directly).

### Import Styles

Add to your main CSS file:

```css
@import '@schandlergarcia/sf-web-components/styles';
```

### Tailwind Configuration

Extend your `tailwind.config.ts`:

```ts
import type { Config } from 'tailwindcss';

export default {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@schandlergarcia/sf-web-components/dist/**/*.{js,jsx}'
  ],
  theme: {
    extend: {}
  }
} satisfies Config;
```

## Components

This library includes:
- UI components (Button, Card, Input, etc.)
- Data components (Tables, Lists)
- Chart components (via Recharts)
- Form components
- Filter components
- Layout components

## Sample Data

The package includes pre-seeded sample data in the `data/` directory:
- **Engine Travel Command Center** sample data with real Salesforce field names
- Dashboard-ready data (map markers, chart data, metrics, etc.)
- Easy to swap for live data later

**Copy to your project:**
```bash
# From your webapp directory
cp node_modules/@schandlergarcia/sf-web-components/data/engine-sample-data.js src/data/
```

See `data/README.md` and `data/USAGE.md` in the package for full documentation.

## Utilities

```tsx
import { cn } from '@schandlergarcia/sf-web-components/lib';

// Merge Tailwind classes with conflict resolution
const className = cn('px-2 py-1', 'px-4'); // Result: 'py-1 px-4'
```

## Development

```bash
# Install dependencies
npm install

# Build the library
npm run build

# Build types only
npm run build:types
```

## Contributing

**⚠️ IMPORTANT: Read [CONTRIBUTING.md](./CONTRIBUTING.md) before making changes.**

### Key Rules
- Component names MUST match `.a4drules/skills/component-library/` documentation
- Library components use **UI prefix** (UIButton, UIInput) - NOT shadcn names
- Update CHANGELOG.md with EVERY change before publishing
- Run verification scripts before committing

### Quick Checks

```bash
# Verify consistency between code, docs, and templates
npm run verify

# Pre-publish verification (runs automatically before publish)
npm run prepublish:check
```

### Documentation Structure
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Source of truth hierarchy
- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Contribution guidelines and checklists
- **[CHANGELOG.md](./CHANGELOG.md)** - Detailed version history
- **[.a4drules/RULES.md](./.a4drules/RULES.md)** - Mandatory project rules

## Publishing

This package publishes to the **public npm registry** at https://registry.npmjs.org.

### Prerequisites
- Be logged in to npm: `npm login`
- Have publish permissions for the `@schandlergarcia` scope

### Publish Process

**The `prepublishOnly` script automatically runs verification checks.**

```bash
# 1. Update CHANGELOG.md with your changes
#    Add entry under ## [X.X.X] - YYYY-MM-DD

# 2. Bump version
npm version patch  # 1.9.43 → 1.9.44
npm version minor  # 1.9.43 → 1.10.0
npm version major  # 1.9.43 → 2.0.0

# 3. Publish (verification runs automatically)
npm publish
```

**The prepublishOnly hook will:**
1. Run consistency verification (`npm run verify`)
2. Check CHANGELOG has entry for current version
3. Verify UIButton.tsx and UIInput.tsx exist
4. Build the package
5. Block publish if any checks fail

### Manual Verification (Optional)

```bash
# Run all pre-publish checks manually
npm run prepublish:check

# Run only consistency checks
npm run verify
```

### If Publish Fails

If verification fails:
1. Read the error output carefully
2. Fix the reported issues
3. See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidance
4. See [.a4drules/RULES.md](./.a4drules/RULES.md) for rules
5. Run `npm run verify` to check fixes
6. Try publishing again

The package is published as **public** and can be installed by anyone:
```bash
npm install @schandlergarcia/sf-web-components
```


## 🤖 AI Agent Skills

This package includes Claude Code agent skills that teach AI how to work with these components.

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

### 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

### Available Skills

Check `.a4drules/skills/` for the full list of included agent skills.


## License

MIT