npm package: @setu/components
Description: Modern React component library built on shadcn/ui with Fictoan compatibility layer
Author: Setu Team
Latest version: 1.7.3

# @setu/components

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

## 🚀 Installation

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

## 📖 Quick Start

### Add CSS Variables

- Create a `globals.css` file in your project (commonly under `src/styles/globals.css`).

Example css file :

```css
@import "@setu/components/styles.css"; // Make sure to import the default @setu/components stylesheet
@import "@setu/components/colors.css"; // Make sure to import for colours utility classes and color props

:root {
    --background: oklch(1 0 0);
    --foreground: oklch(0.145 0 0);
    --primary: oklch(0.205 0 0);
    --primary-foreground: oklch(0.985 0 0);
    --secondary: oklch(0.97 0 0);
    --secondary-foreground: oklch(0.205 0 0);
}

.dark {
    --background: oklch(0.145 0 0);
    --foreground: oklch(0.985 0 0);
    --primary: oklch(0.922 0 0);
    --primary-foreground: oklch(0.205 0 0);
    --secondary: oklch(0.269 0 0);
    --secondary-foreground: oklch(0.985 0 0);
}

@layer base {
    * {
        border-color: var(--setu-color-border);
        box-sizing: border-box;
    }

    body {
        background-color: var(--setu-color-background);
        color: var(--setu-color-foreground);
    }
}
```

- Import your `globals.css` file in your main entry file (e.g., `app.tsx` or `main.tsx`).
- Restart your dev server after making these changes to ensure the theme provider is applied.

**Attach ThemeProvider to your repo:**

- Add the `ThemeProvider` setup to your `App.tsx` or main entry file.
- Make sure your CSS includes the correct theme variable definitions (see earlier section for `globals.css`).

> 💡 For advanced usage, you can customize the `defaultTheme` and `storageKey` props. The provider will always prioritize the user’s saved preference over the default.

---

### Usage

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

function MyComponent() {
    return (
        <Card className="w-96">
            <CardContent className="p-6 space-y-4">
                <div className="space-y-2">
                    <h3 className="text-lg font-semibold">Welcome to @setu/components</h3>
                    <Badge variant="secondary">Ready to use</Badge>
                </div>

                <Alert>
                    <AlertTitle>Success!</AlertTitle>
                    <AlertDescription>Your changes have been saved.</AlertDescription>
                </Alert>

                <div className="space-y-2">
                    <Input placeholder="Enter your name" />
                    <Button variant="default" size="lg" className="w-full">
                        Click me
                    </Button>
                </div>
            </CardContent>
        </Card>
    );
}
```

> 💡 **Explore All Components**: Visit [ui.setu.co](https://ui.setu.co) to see the complete list of 50+ components with interactive demos, code examples, and detailed documentation.

## 🔄 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 22
- Yarn v4

### Setting up the Project

To set up the development environment, run:

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

**For VS Code users:**

To enable proper TypeScript and ESLint integration with Yarn PnP, run:

```bash
yarn dlx @yarnpkg/sdks vscode
```

Then, open the Command Palette in VS Code and select:

> **TypeScript: Select TypeScript Version** → **Use Workspace Version**

### 🏗️ Architecture

```
setu-components/
├── src/                        # Source code
│   ├── components/            # React components
│   │   ├── ui/               # UI components (50+ components)
│   │   │   ├── __tests__/    # Component tests
│   │   │   ├── *.tsx         # Component implementations
│   │   │   └── *.stories.tsx # Storybook stories
│   │   ├── theme-provider.tsx # Theme context provider
│   │   └── index.ts          # Component exports
│   ├── lib/                  # Core utilities
│   │   ├── utils.ts          # Utility functions
│   │   └── fictoan-schema.ts # Fictoan compatibility mappings
│   ├── styles/               # Global styles
│   │   └── globals.css       # Base CSS + Tailwind + Themes
│   └── index.ts              # Main export
├── dev-server/               # Development server
│   ├── demos/                # Component demos (50+ demos)
│   └── components/           # Dev server components
├── .storybook/              # Storybook configuration
└── dist/                    # Built output
```

### Scripts

```bash
# Development
yarn dev             # Start Vite dev server
yarn storybook       # Start Storybook

# Building
yarn build           # Build library 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
```

---

### Contributions 🤝

We welcome contributions! Please follow the guidelines suggested by SetuHQ:

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

### Pull Request & Commit Guidelines

We use [semantic versioning](https://semver.org/) and rely on [semantic-release](https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/github-actions) to automate releases based on commit messages. To ensure this works smoothly:

1. **Follow Conventional Commits:** Refer to the [Angular commit message guidelines](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md)
2. **PR Titles Matter:** - We squash commits on merge. The PR title becomes the commit message in the main branch. - Make sure your PR title follows the conventional commit format. - Include a JIRA ticket ID in the title as scope.

    **Example:**

    ```bash
    feat(PROJECT-1234): add new button component
    ```

3. **Why this matters:**
    - Consistent commit messages keep our history clean and readable.
    - Automated releases and changelogs depend on this structure.

If you’re unsure, refer to the [conventional commits documentation](https://www.conventionalcommits.org/en/v1.0.0/) or check recent merged PRs for examples.

## Deployment 🚀

Our deployment process is fully automated via GitHub Actions:

1. **Docs & Storybook Deployment:**
    - On every push to the main branch, the CI/CD pipeline will:
        - Build and deploy the documentation to [ui.setu.co](http://ui.setu.co)
        - Build and deploy Storybook to [ui-storybook.setu.co](http://ui-storybook.setu.co)

2. **Publishing the Library:**
    - Library releases are not automatic.
    - To publish a new version to npm:
        1. Ensure all checks have passed on your PR and merge to main.
        2. Go to the **Actions** tab on GitHub.
        3. Manually trigger the **Release** workflow.
        4. The workflow will handle versioning, changelog, and npm publish using semantic-release.

> ℹ️ **Tip:** Only maintainers with the right permissions can trigger the publish workflow.

## 📚 Documentation

- [Storybook](https://ui-storybook.setu.co) - Component documentation
- [Theme System](#add-css-variables) - Design tokens and theming
- [Contributing](#Prerequisites) - Development guidelines

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