@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

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 :

@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

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

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

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

2. Phase 2: Enhanced APIs

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

   // 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:

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:

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

# 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 and rely on semantic-release to automate releases based on commit messages. To ensure this works smoothly:

1. Follow Conventional Commits: Refer to the Angular commit message guidelines

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:

   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 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
     • Build and deploy Storybook to 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 - Component documentation
• Theme System - Design tokens and theming
• Contributing - Development guidelines

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• SetuHQ - Main website
• GitHub - Source code
• npm - Package registry
• Issues - Bug reports & feature requests

⭐ Show your support

Give a ⭐️ if this project helped you!

Built with ❤️ by the Setu team