npm package: @shared-dashboard-solid/ui-standalone
Description: SolidJS Component Library (Design System) - Modular and treeshakeable component library with TypeScript, Tailwind CSS, and Storybook
Latest version: 1.2.18

# SolidJS Component Library (Design System)

A modular and treeshakeable SolidJS component library built with TypeScript, Tailwind CSS, SCSS Modules, and Storybook.

## ✨ Latest Version: 1.2.14

**Version 1.2.14 includes critical fixes for:**
- ✅ Consistent export names (Button, Badge, Alert)
- ✅ TypeScript declaration files
- ✅ Bundle optimization with shared dependencies
- ✅ Individual component publishing support

## 🚀 Quick Start

### Option 1: UI-Standalone Package (Recommended)

```bash
npm install @shared-dashboard-solid/ui-standalone@1.2.14
```

```tsx
// Import styles (required)
import '@shared-dashboard-solid/ui-standalone/styles';

// Import components
import { Button, Badge, Alert } from '@shared-dashboard-solid/ui-standalone';

// OR import individual components for optimal tree-shaking
import { Button } from '@shared-dashboard-solid/ui-standalone/Button';
import { Badge } from '@shared-dashboard-solid/ui-standalone/Badge';
```

### Option 2: Individual Component Packages

```bash
npm install @shared-dashboard-solid/button@1.0.10
npm install @shared-dashboard-solid/badge
npm install @shared-dashboard-solid/alert
```

```tsx
import { Button } from '@shared-dashboard-solid/button';
import { Badge } from '@shared-dashboard-solid/badge';
import '@shared-dashboard-solid/button/ui-standalone.css'; // Required
```

## 📦 Bundle Sizes (v1.2.14+)

- **Button**: ~13.5KB total (1KB + 12.5KB shared)
- **Badge**: ~13.4KB total (0.9KB + 12.5KB shared)
- **Alert**: ~13.6KB total (1.1KB + 12.5KB shared)
- **Full Bundle**: ~15KB (optimal for multiple components)

## 🎯 Usage Examples

### Button Component

```tsx
import { Button } from '@shared-dashboard-solid/ui-standalone/Button';

<Button variant="primary" size="lg" onClick={() => console.log('Clicked!')}>
  Click me!
</Button>
```

### Badge Component

```tsx
import { Badge } from '@shared-dashboard-solid/ui-standalone/Badge';

<Badge color="success" size="sm">
  Success
</Badge>
```

### Alert Component

```tsx
import { Alert } from '@shared-dashboard-solid/ui-standalone/Alert';

<Alert variant="error" title="Error">
  Something went wrong. Please try again.
</Alert>
```

## 🔧 TypeScript Support

Full TypeScript support with proper component props:

```tsx
import { Button, type ButtonProps } from '@shared-dashboard-solid/ui-standalone/Button';

// Full autocomplete and type checking
const CustomButton: Component<ButtonProps> = (props) => {
  return <Button {...props} />;
};
```

## 🐛 Troubleshooting

**Common Issues & Solutions:**

### ❌ "Cannot find declaration file"
**Solution**: Update to v1.2.14+:
```bash
npm install @shared-dashboard-solid/ui-standalone@1.2.14
```

### ❌ "Does not provide an export named 'Badge'"
**Solution**: Use v1.2.14+ with consistent exports:
```bash
npm install @shared-dashboard-solid/ui-standalone@1.2.14
```

### ❌ Bundle size too large
**Solution**: Version 1.2.14+ uses shared dependencies for optimal tree-shaking.

**For complete troubleshooting guide, see [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md)**

## 🛠️ Available Scripts

### Building
```bash
npm run build:all          # Build all components
npm run build:individual    # Build individual components
npm run build:standalone    # Build standalone bundle
npm run build:component     # Build specific component
```

### Publishing
```bash
npm run publish:standalone  # Publish full package
npm run publish:button      # Publish individual Button
npm run publish:badge       # Publish individual Badge
npm run publish:alert       # Publish individual Alert
```

### Development
```bash
npm run dev                 # Start dev server
npm run storybook           # Start Storybook
npm run test                # Run tests
npm run test:coverage       # Run tests with coverage
npm run generate            # Generate new component (see below)
```

### Component Generation
```bash
# Generate new components with full boilerplate
npm run generate <atomic-type> <component-name>

# Examples:
npm run generate atoms Input          # Generate Input atom
npm run generate molecules Card       # Generate Card molecule
npm run generate organisms Header     # Generate Header organism
npm run generate templates PageLayout # Generate PageLayout template
npm run generate pages HomePage      # Generate HomePage page
```

**Atomic Types Available:**
- `atoms` - Basic UI elements (Button, Input, Icon)
- `molecules` - Simple combinations (Card, FormField, SearchBox)
- `organisms` - Complex components (Header, Sidebar, Table)
- `templates` - Layout components (PageLayout, AuthLayout)
- `pages` - Complete pages (HomePage, LoginPage)

**Generated Files:**
- Component file (.tsx) with TypeScript interfaces
- SCSS module (.module.scss) with design tokens
- Index file (index.ts) for exports
- Test file (.test.tsx) with Solid Testing Library
- Storybook file (.stories.tsx) for documentation
- Automatic updates to main index.ts, vite.config.ts, and package.json

## 📚 Available Components

### Atoms

#### Button
- **Variants**: `primary`, `secondary`, `ghost`
- **Sizes**: `sm`, `md`, `lg`
- **Extends**: `JSX.ButtonHTMLAttributes<HTMLButtonElement>`

#### Badge
- **Colors**: `default`, `success`, `warning`, `error`
- **Sizes**: `sm`, `md`
- **Extends**: `JSX.HTMLAttributes<HTMLSpanElement>`

#### Alert
- **Variants**: `primary`, `secondary`, `success`, `warning`, `error`, `outline`
- **Sizes**: `sm`, `md`, `lg`
- **Props**: `title`, `children`

## 🎨 Design System Features

- ✅ **SolidJS** with TypeScript
- ✅ **Modular Builds** - Individual components can be built separately
- ✅ **Treeshakeable** - Side-effect free with proper exports
- ✅ **Design System** - Comprehensive design tokens and consistent styling
- ✅ **Tailwind CSS** + SCSS Modules with design tokens
- ✅ **Storybook** for component documentation and development
- ✅ **Vite** for fast building and development
- ✅ **Unit Testing** with Vitest and Solid Testing Library

## 🎨 Design Tokens

All styling is based on design tokens defined in `tailwind.config.js`:

- **Colors**: Primary, secondary, success, warning, error, and neutral palettes
- **Typography**: Consistent font sizes, weights, and line heights
- **Spacing**: 4px base unit with consistent scale
- **Shadows**: Pre-defined shadow styles for different components
- **Border Radius**: Consistent border radius scale
- **Animations**: Standardized transitions and keyframes

## 🔒 Security

**npm Audit Status**: 1 low severity vulnerability in devDependencies
- **Impact**: Development only, doesn't affect production runtime
- **Solution**: Safe to use, or run `npm audit fix --force` if needed

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📞 Support

For issues not covered in [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md):
1. Check you're using version 1.2.14+
2. Verify imports match documented patterns
3. Ensure styles are imported correctly
4. Review your TypeScript configuration

---

**Version History:**
- **1.2.14** - Final stable version with all fixes
- **1.2.13** - Fixed export name inconsistencies
- **1.2.12** - Added proper TypeScript declarations
- **1.2.11** - Improved bundle structure
- **1.2.10** - Enhanced individual component support
- **1.2.9** - Bundle optimization fixes
- **1.2.8** - Security improvements
- **1.2.7** - Initial stable release