# @setu/components

[![npm version](https://badge.fury.io/js/%40setu%2Fcomponents.svg)](https://badge.fury.io/js/%40setu%2Fcomponents)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A modern React component library built on **shadcn/ui** with **Fictoan compatibility layer** for seamless migration.

## ✨ Features

- 🎨 **Modern Design**: Built on shadcn/ui with Radix UI primitives
- 🔄 **Fictoan Compatible**: 100% backward compatibility with Fictoan props
- 🎯 **TypeScript First**: Full TypeScript support with comprehensive types
- 🌙 **Theme Support**: Built-in dark mode and custom theme support
- 📦 **Tree Shakable**: Optimized bundle size with selective imports
- ♿ **Accessible**: ARIA compliant with keyboard navigation
- 📱 **Responsive**: Mobile-first design approach

## 📊 Bundle Size

- **ESM**: 250.05 KB (54.66 KB gzipped)
- **CJS**: 110.52 KB (35.37 KB gzipped)
- **UMD**: 110.46 KB (35.52 KB gzipped)

## 🚀 Installation

```bash
npm install @setu/components
# or
yarn add @setu/components
# or
pnpm add @setu/components
```

## 📖 Quick Start

### 1. Install Dependencies

```bash
npm install tailwindcss
```

### 3. Add CSS Variables

```css
/* Add to your global CSS */
@tailwind base;
@tailwind components;
@tailwind utilities;

:root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --card: 0 0% 100%;
    --card-foreground: 222.2 84% 4.9%;
    --popover: 0 0% 100%;
    --popover-foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96%;
    --secondary-foreground: 222.2 84% 4.9%;
    --muted: 210 40% 96%;
    --muted-foreground: 215.4 16.3% 46.9%;
    --accent: 210 40% 96%;
    --accent-foreground: 222.2 84% 4.9%;
    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 210 40% 98%;
    --border: 214.3 31.8% 91.4%;
    --input: 214.3 31.8% 91.4%;
    --ring: 221.2 83.2% 53.3%;
    --radius: 0.5rem;
}

.dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --card: 222.2 84% 4.9%;
    --card-foreground: 210 40% 98%;
    --popover: 222.2 84% 4.9%;
    --popover-foreground: 210 40% 98%;
    --primary: 217.2 91.2% 59.8%;
    --primary-foreground: 222.2 84% 4.9%;
    --secondary: 217.2 32.6% 17.5%;
    --secondary-foreground: 210 40% 98%;
    --muted: 217.2 32.6% 17.5%;
    --muted-foreground: 215 20.2% 65.1%;
    --accent: 217.2 32.6% 17.5%;
    --accent-foreground: 210 40% 98%;
    --destructive: 0 62.8% 30.6%;
    --destructive-foreground: 210 40% 98%;
    --border: 217.2 32.6% 17.5%;
    --input: 217.2 32.6% 17.5%;
    --ring: 224.3 76.3% 94.1%;
}
```

### 4. Setup Theme Provider

```tsx
import { ThemeProvider } from "@setu/components";

function App() {
    return (
        <ThemeProvider
            defaultTheme="system"
            storageKey="my-app-theme"
            enableSystem={true}
            disableTransitionOnChange={false}
        >
            <YourApp />
        </ThemeProvider>
    );
}
```

### 5. Use Components

```tsx
import { Button, Card, CardContent, Alert } from "@setu/components";

function MyComponent() {
    return (
        <Card className="w-96">
            <CardContent className="p-6">
                <Alert>
                    <AlertTitle>Success!</AlertTitle>
                    <AlertDescription>Your changes have been saved.</AlertDescription>
                </Alert>
                <Button variant="default" size="lg">
                    Click me
                </Button>
            </CardContent>
        </Card>
    );
}
```

## 🎨 Theme System

```tsx
import { useTheme } from "@setu/components";

function ThemeToggle() {
    const { theme, setTheme } = useTheme();

    return (
        <Button onClick={() => setTheme(theme === "dark" ? "light" : "dark")} variant="outline">
            Toggle {theme === "dark" ? "Light" : "Dark"} Mode
        </Button>
    );
}
```

## 🔄 Fictoan Migration

### Backward Compatibility

Keep your existing Fictoan code working unchanged:

```tsx
// Your existing Fictoan code works as-is!
<Button colour="blue" kind="primary">
  Legacy Button
</Button>

<Card margin="medium" padding="large" shadow-sm="soft">
  Legacy Card Content
</Card>
```

### Migration Strategy

1. **Phase 1: Drop-in Replacement**

    ```bash
    # Replace Fictoan import
    - import { Button } from 'fictoan-react';
    + import { Button } from '@setu/components';
    ```

2. **Phase 2: Enhanced APIs**

    ```tsx
    // Gradually adopt new props while keeping Fictoan props
    <Button
        colour="blue" // Fictoan prop (still works)
        variant="default" // New shadcn/ui prop
    >
        Hybrid Usage
    </Button>
    ```

3. **Phase 3: Full Migration**
    ```tsx
    // Complete transition to shadcn/ui API
    <Button variant="default" size="lg">
        Modern Button
    </Button>
    ```

## 🛠️ Development

### Prerequisites

- Node.js 18+
- npm/yarn/pnpm

### Setup

```bash
git clone https://github.com/SetuHQ/setu-components.git
cd setu-components
yarn install

# For VS Code users (enables proper TypeScript/ESLint integration with Yarn PnP)
yarn dlx @yarnpkg/sdks vscode
```

### Scripts

```bash
# Development

# Enable Corepack and use Yarn 4 (run once)
corepack enable
corepack prepare yarn@4.9.4 --activate

# For IDE integration (run once)
yarn dlx @yarnpkg/sdks vscode

# Setup Git hooks (run once)
yarn setup-hooks

yarn dev             # Start Vite dev server
yarn storybook       # Start Storybook

# Building
yarn build           # Build for production
yarn preview         # Preview production build

# Quality
yarn lint            # Run ESLint
yarn type-check      # TypeScript checking
yarn test            # Run tests

# Analysis
npm run build:analyze # Bundle size analysis + build
npm run treeshake     # Tree-shaking verification

# Publishing
npm run prepublishOnly # Pre-publish checks
npm publish           # Publish to npm
```

## 🧪 Testing the Library

### Local Testing

Create a test project to verify the library works:

```bash
# Create test project
npx create-react-app test-setu-components --template typescript
cd test-setu-components

# Install the library
npm install @setu/components

# Install required dependencies
npm install tailwindcss clsx tailwind-merge class-variance-authority

# Setup Tailwind CSS
npx tailwindcss init
```

### Test Components

```tsx
// src/App.tsx
import { ThemeProvider, Button, Card, CardContent } from "@setu/components";

function App() {
    return (
        <ThemeProvider>
            <div className="p-8">
                <Card className="w-96">
                    <CardContent className="p-6">
                        <h1 className="text-2xl font-bold mb-4">Testing @setu/components</h1>

                        {/* Test shadcn/ui API */}
                        <Button variant="default" className="mr-2">
                            shadcn/ui Button
                        </Button>

                        {/* Test Fictoan compatibility */}
                        <Button colour="blue" kind="primary">
                            Fictoan Button
                        </Button>
                    </CardContent>
                </Card>
            </div>
        </ThemeProvider>
    );
}

export default App;
```

## 📚 Documentation

- [Storybook](http://localhost:6006) - Component documentation
- [Theme System](./docs/theme-system.md) - Design tokens and theming
- [Migration Guide](./docs/migration.md) - Fictoan to shadcn/ui migration
- [Contributing](./CONTRIBUTING.md) - Development guidelines

## 🏗️ Architecture

```
setu-components/
├── src/                        # Source code
│   ├── index.ts               # Main export
│   ├── themes/                # Theme system
│   │   ├── index.ts          # Theme types
│   │   ├── light-theme.ts    # Light theme tokens
│   │   ├── dark-theme.ts     # Dark theme tokens
│   │   ├── theme-provider.tsx # React context
│   │   └── theme-utils.ts    # Utility functions
│   ├── components/           # React components (coming soon)
│   └── styles/              # Global styles
│       └── globals.css      # Base CSS + Tailwind
├── scripts/                   # Development & deployment scripts
│   ├── size-check.js         # Bundle size analysis
│   ├── treeshake-check.js    # Tree-shaking verification
│   └── deployment/           # Release & publishing scripts
│       ├── setup-github.sh   # GitHub repository setup
│       ├── setup-npm.sh      # npm publishing setup
│       └── release.sh        # Complete release workflow
├── .storybook/               # Storybook configuration
├── docs/                     # Documentation files
└── dist/                     # Built output (generated)
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.

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

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

## 🔗 Links

- [SetuHQ](https://setu.co) - Main website
- [GitHub](https://github.com/SetuHQ/setu-components) - Source code
- [npm](https://www.npmjs.com/package/@setu/components) - Package registry
- [Issues](https://github.com/SetuHQ/setu-components/issues) - Bug reports & feature requests

## ⭐ Show your support

Give a ⭐️ if this project helped you!

---

Built with ❤️ by the [Setu team](https://setu.co)
