npm package: @sehgaltech/psui
Description: A scalable and customizable UI library built with Tailwind CSS v4, TypeScript, and React
Author: purvisehgal
Latest version: 1.0.5

# PSUI

A scalable and customizable UI library built with Tailwind CSS v4, TypeScript, and React.

📚 **[Documentation](https://psui.sehgaltech.com/)** | 📝 **[Changelog](https://psui.sehgaltech.com/docs/changelog)**

## Features

- 🎨 **Tailwind CSS v4** - Modern CSS-first configuration with `@theme` blocks
- 📦 **TypeScript** - Full type safety and excellent developer experience
- ⚡ **tsup** - Fast and efficient builds with ESM/CJS dual output
- 📚 **Documentation** - Custom interactive component documentation using Vite
- 🧪 **Vitest** - Fast unit testing with React Testing Library
- 🎯 **Tree-shakeable** - Optimized bundle size with side-effect free exports
- 🎨 **Customizable** - Easy theme customization via CSS variables

## Installation

```bash
npm install @sehgaltech/psui
# or
yarn add @sehgaltech/psui
# or
pnpm add @sehgaltech/psui
```

## Usage

### Basic Setup

1. Import the library styles in your application's main CSS file or entry point:

```tsx
// In your main CSS file (e.g., index.css or app.css)
@import '@sehgaltech/psui/styles';
```

OR in your JavaScript/TypeScript entry file:

```tsx
// In your main entry file (e.g., main.tsx or index.tsx)
import './index.css'; // This initializes Tailwind and scans psui
import '@sehgaltech/psui/styles'; // This provides the colors/themes for psui
```

**Note:** Make sure your build tool supports Tailwind CSS v4. If you're using Vite, install `@tailwindcss/vite` plugin:

```bash
npm install -D @tailwindcss/vite
```

Then add it to your `vite.config.ts`:

```ts
import tailwindcss from '@tailwindcss/vite';

export default {
  plugins: [tailwindcss()],
};
```

2. Use components in your React application:

```tsx
import { Button } from '@sehgaltech/psui';

function App() {
  return (
    <div>
      <Button variant="solid" type="primary" size="md">
        Click me
      </Button>
    </div>
  );
}
```

### Button Component

The Button component supports multiple types, variants, sizes, and states:

```tsx
import { Button } from '@sehgaltech/psui';

// Types (colors)
<Button type="primary">Primary</Button>
<Button type="secondary">Secondary</Button>
<Button type="success">Success</Button>
<Button type="danger">Danger</Button>
<Button type="warning">Warning</Button>
<Button type="info">Info</Button>
<Button type="ghost">Ghost</Button>

// Variants (styles)
<Button variant="solid">Solid (default)</Button>
<Button variant="outlined">Outlined</Button>
<Button variant="dashed">Dashed</Button>
<Button variant="text">Text</Button>
<Button variant="link">Link</Button>

// Sizes
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

// States & Features
<Button loading>Loading...</Button>
<Button disabled>Disabled</Button>
<Button fullWidth>Full Width</Button>
<Button success>Success State</Button>
<Button startIcon={<YourIcon />}>With Icon</Button>
```

## Themes

PSUI ships with two themes: **Winter** (light) and **Starlight** (dark). Both use OKLCH colors and semantic tokens (base, primary, secondary, accent, neutral, info, success, warning, error).

### Switching themes

Set `data-theme` on a root element (e.g. `<html>` or a wrapper):

```tsx
// Light (default)
<html data-theme="winter">

// Dark
<html data-theme="starlight">
```

You can switch at runtime:

```tsx
document.documentElement.setAttribute('data-theme', 'starlight');
```

### Theme tokens

- **Colors**: `base-100`, `base-200`, `base-300`, `base-content`, `primary`, `primary-content`, `secondary`, `secondary-content`, `accent`, `accent-content`, `neutral`, `neutral-content`, `info`, `info-content`, `success`, `success-content`, `warning`, `warning-content`, `error`, `error-content`
- **Radius**: `--radius-selector`, `--radius-field`, `--radius-box`
- **Sizes**: `--size-selector`, `--size-field`
- **Border**: `--border-width`

### Customization

Override theme variables for a given theme:

```css
[data-theme="winter"] {
  --theme-primary: oklch(70% 0.12 260);
}
```

## Development

### Prerequisites

- Node.js 18+ 
- npm, yarn, or pnpm

### Setup

```bash
# Install dependencies
npm install

# Start development build in watch mode
npm run dev

# Run documentation site locally
cd docs && npm run dev

# Run tests
npm test

# Type check
npm run type-check

# Build library
npm run build
```

### Project Structure

```
psui/
├── src/
│   ├── components/       # React components
│   │   ├── Button/
│   │   └── index.ts
│   ├── styles/           # Tailwind CSS styles
│   │   ├── base.css      # Tailwind import
│   │   └── theme.css     # Theme tokens
│   ├── types/            # TypeScript types
│   ├── utils/            # Shared utilities
│   └── index.ts          # Main entry point
├── docs/                 # Custom Vite React documentation site
└── dist/                 # Build output
```

### Adding New Components

1. Create component directory in `src/components/`:

```bash
mkdir src/components/MyComponent
```

1. Create component file:

```tsx
// src/components/MyComponent/MyComponent.tsx
import { forwardRef } from 'react';
import type { ComponentProps } from '../../types';

export interface MyComponentProps extends ComponentProps<'div'> {
  // Your props
}

export const MyComponent = forwardRef<HTMLDivElement, MyComponentProps>(
  ({ className, ...props }, ref) => {
    return <div ref={ref} className={className} {...props} />;
  }
);

MyComponent.displayName = 'MyComponent';
```

1. Export from component index:

```tsx
// src/components/MyComponent/index.ts
export { MyComponent } from './MyComponent';
export type { MyComponentProps } from './MyComponent';
```

1. Export from main components index:

```tsx
// src/components/index.ts
export { MyComponent } from './MyComponent';
export type { MyComponentProps } from './MyComponent';
```

1. Export from main library entry:

```tsx
// src/index.ts
export { MyComponent } from './components';
export type { MyComponentProps } from './components';
```

1. Create a documentation page in `docs/src/pages/MyComponentPage.tsx` and add it to the routing in `docs/src/App.tsx`.


## Building and Publishing

### Build

```bash
npm run build
```

This generates:

- `dist/index.js` - CommonJS bundle
- `dist/index.mjs` - ES Module bundle
- `dist/index.d.ts` - TypeScript declarations
- `dist/styles.css` - Compiled CSS

### Publishing

1. Update version in `package.json`
2. Build the library: `npm run build`
3. Publish to npm: `npm publish`

## Deployment (Documentation)

Deploy the custom component documentation site (`docs/`) to Vercel so others can browse the library online.

### Prerequisites

- Project pushed to GitHub, GitLab, or Bitbucket
- [Vercel](https://vercel.com) account

### Steps

1. **Deploy via Vercel**
  - In [Vercel](https://vercel.com): **Add New Project** → import your repository.  
  - Configure the project:
    - **Framework Preset:** Vite
    - **Root Directory:** `docs`
    - **Build Command:** `npm run build`
    - **Output Directory:** `dist`
    - **Install Command:** `npm install`
  - Deploy. The published URL will serve your custom Vite React documentation site.


## TypeScript Support

PSUI is written in TypeScript and provides full type definitions. All components export their prop types for use in your applications:

```tsx
import type { ButtonProps } from '@sehgaltech/psui';

const MyButton: React.FC<ButtonProps> = (props) => {
  // Type-safe component
};
```

## Browser Support

- Safari 16.4+
- Chrome 111+
- Firefox 128+

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.