# @vectorshift/ui Design System

A comprehensive UI component library for VectorShift applications built with React, TypeScript, and Tailwind CSS.

## 📦 Installation

```bash
# Install from npm registry
npm install @vectorshift/ui
```

## 🤝 Team Workflow

### For Design System Developers (Working Only on Design System)

1. Create/modify components in `src/Primitives/`
2. **Add exports to `src/Main.ts`**
3. Test components in Storybook: `npm run storybook`
4. Build and publish: `npm run publish:patch` / `npm run publish:minor` / `npm run publish:major`
5. No need for yalc or local linking

### For Design System + App Developers (Working on Both)

1. Set up local development with `yalc` (see [Local Development](#-local-development-testing-changes-without-publishing) section)
2. Create/modify components in design system
3. **Add exports to `src/Main.ts`**
4. Test live changes in app using `npm run build:watch`
5. Publish when ready: `npm run publish:patch` / `npm run publish:minor` / `npm run publish:major`

### For App Developers (Working Only on Apps)

1. Use whatever version is specified in your app's `package.json`
2. Run `npm install` to get the design system package
3. Import and use components normally
4. If you encounter package-related issues, report to design system team
5. No need for yalc or local development setup

### Publishing Guidelines

- **Regular releases:** Use `npm run publish:patch` / `npm run publish:minor` / `npm run publish:major`
- **Testing releases:** Use `npm run publish:dev` only when someone needs an updated package for local testing without affecting others

## 🚀 Usage

```tsx
import { Button, Input } from '@vectorshift/ui';
import '@vectorshift/ui/style.css';

function App() {
  return (
    <div>
      <Button variant="primary">Click me</Button>
      <Input placeholder="Enter text..." />
    </div>
  );
}
```

## 🛠️ Development Setup

### Prerequisites

- Node.js 22.14.0 (exact version required)
- npm package manager

### Installation

```bash
# Install dependencies
npm install

# Start Storybook for development
npm run storybook
```

**💡 Note:** Check the [Team Workflow](#-team-workflow) section above to understand what tools you need based on your role.

## 🔧 Building the Package

```bash
# Build the package
npm run build

# Build in watch mode (rebuilds on file changes)
npm run build:watch

# Check build output
ls dist/
```

## 📝 Adding New Components

### 1. Create Your Component

```bash
# Example: Creating a new Card component
mkdir src/Primitives/Card
touch src/Primitives/Card/Card.tsx
touch src/Primitives/Card/Card.stories.tsx
```

### 2. **IMPORTANT: Export Your Component**

After creating a new component, you **must** add it to the main export file:

```typescript
// src/Main.ts
export * from './Primitives/Card/Card'; // Add this line for new components
export * from './Primitives/Button/Button';
export * from './Primitives/Input/Input';
// ... other exports
```

**⚠️ If you forget this step, your component won't be available when the package is installed!**

### 3. Create Stories (Optional but Recommended)

```tsx
// src/Primitives/Card/Card.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Card } from './Card';

const meta: Meta<typeof Card> = {
  title: 'Primitives/Card',
  component: Card,
};

export default meta;
```

## 🔗 Local Development (Testing Changes Without Publishing)

### Using `yalc` for Local Development

Yalc provides the smoothest local development workflow with automatic updates.

#### One-Time Setup:

```bash
# Install yalc globally (one time only)
npm install -g yalc
```

#### Development Workflow:

**Option 1: Auto-rebuild + Auto-connect (Recommended) 🚀**

```bash
# Step 1: Start auto-build with automatic yalc publishing
cd typescript/design-system
npm run build:watch

# Step 2: Link to your app (in a separate terminal)
cd app
npm run yalc:link

# That's it! Changes automatically appear in your app whenever you make changes in design system!
```

**Option 2: Manual Build + Publish**

```bash
# Step 1: Build and publish to yalc store
cd typescript/design-system
npm run build
npm run yalc:publish

# Step 2: Link to your app
cd app
npm run yalc:link

# Step 3: Repeat step 1 after each change you want to test
```

#### Clean Up When Done:

```bash
# Unlink from app
cd app
npm run yalc:unlink

# Clean up design system (optional)
cd typescript/design-system
npm run yalc:unpublish
```

### 💡 Pro Tips:

- Use **Option 1** for active development - it automatically rebuilds and publishes after every file save
- Use **Option 2** when you want more control over when changes are published
- No need to run `npm install` after linking with yalc!
- The `build:watch` command includes TypeScript compilation, bundling, and automatic yalc publishing

## 📦 Publishing to NPM

### 🔐 Authentication Required

**Only use this npm account for publishing:**

- **Email:** `frontend.developers2@vectorshift.ai`
- **Username:** `frontend_dev_vectorshift`
- **Password:** Contact the design system team to get the password

```bash
# Login with the team account (one time setup)
npm login
# Enter the credentials above when prompted

# Verify you're logged in correctly
npm whoami
# Should show: frontend_dev_vectorshift
```

### 📋 Publishing Commands

#### For Development/Testing

```bash
npm run publish:dev
```

**When to use:**

- Testing new features
- Sharing work-in-progress with team
- Before creating official releases
- Creates version like: `3.0.3-dev.abc123.1640000000`

#### For Bug Fixes

```bash
npm run publish:patch
```

**When to use:**

- Fixing bugs in existing components
- Small improvements that don't change functionality
- Version bump: `3.0.3` → `3.0.4`

#### For New Features

```bash
npm run publish:minor
```

**When to use:**

- Adding new components
- Adding new props to existing components
- Feature improvements
- Version bump: `3.0.3` → `3.1.0`

#### For Major Changes

```bash
npm run publish:major
```

**When to use:**

- Breaking changes to component APIs
- Removing components or props
- Major restructuring
- Version bump: `3.0.3` → `4.0.0`

### 🔍 Checking Published Versions

```bash
# See all published versions
npm run check-package

# View specific version details
npm view @vectorshift/ui@latest
npm view @vectorshift/ui@dev
```

## 📱 Using Published Versions in Apps

### Development

```json
// package.json
{
  "dependencies": {
    "@vectorshift/ui": "^3.0.3-dev"
  }
}
```

### Production

```json
// package.json
{
  "dependencies": {
    "@vectorshift/ui": "^3.0.0"
  }
}
```

### Update to Latest

```bash
# In your app directory
cd app

# Update to latest dev version
npm install @vectorshift/ui@dev

# Update to latest stable version
npm install @vectorshift/ui@latest

# Update to specific version
npm install @vectorshift/ui@3.0.5
```

## 🧪 Testing

```bash
# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Type checking
npm run typecheck
```

## 📁 Project Structure

```
typescript/design-system/
├── src/
│   ├── Main.ts              # 🔴 Main export file - ADD NEW COMPONENTS HERE
│   ├── Primitives/          # Basic UI components
│   │   ├── Button/
│   │   ├── Input/
│   │   └── Card/
│   ├── Composed/            # Complex composed components
│   └── hooks/               # Shared React hooks
├── dist/                    # Built package (auto-generated)
├── package.json             # Package configuration
└── README.md               # This file
```

## 🚨 Common Issues & Solutions

### "Component not found" after publishing

**Problem:** You created a component but it's not available after installing the package.
**Solution:** Check if you exported it in `src/Main.ts`:

```typescript
// Add this line:
export * from './Primitives/YourComponent/YourComponent';
```

### "rimraf: command not found"

**Problem:** Build fails with rimraf error.
**Solution:** Run `npm install` to install dependencies.

### Local changes not reflecting in app

**Problem:** Made changes but app doesn't see them.
**Solution:** Run `npm run build` in the design system (changes should appear automatically)

### React-related errors ("Element type is invalid", "Can't resolve 'react'")

**Problem:** Getting React conflicts.
**Solution:** This is rare with yalc but can happen. Clean everything and restart:

```bash
# Clean up yalc
cd app && npm run yalc:unlink
cd ../typescript/design-system && npm run yalc:unpublish

# Clean install both projects
cd ../app && rm -rf node_modules package-lock.json && npm install
cd ../typescript/design-system && rm -rf node_modules package-lock.json && npm install

# Set up yalc again
cd typescript/design-system && npm run build && npm run yalc:publish
cd ../app && npm run yalc:link
```

### Components showing as undefined

**Problem:** Imported components are undefined even though they exist.
**Solution:**

1. Check if you exported the component in `src/Main.ts`
2. Rebuild the design system: `npm run build`
3. Changes should appear automatically in your app
4. Check import/export syntax matches

### "yalc command not found"

**Problem:** yalc commands don't work.
**Solution:** Install yalc globally: `npm install -g yalc`

### Publishing fails with 404 error

**Problem:** Scope @vectorshift not found.
**Solution:** Make sure you're logged in with the correct npm account:

```bash
npm whoami  # Should show: frontend_dev_vectorshift
```

## Quick Commands Cheat Sheet

### Local Development Setup (One-time)

```bash
# In design system directory
cd typescript/design-system
npm run build && npm run yalc:publish

# In app directory
cd app
npm run yalc:link
```

### Daily Development Workflow

```bash
# Start auto-rebuild (recommended)
cd typescript/design-system
npm run build:watch  # Changes appear automatically in linked apps

# Or manual builds
npm run build  # Changes appear automatically in linked apps
```

### Other Development Commands

```bash
# View components in Storybook
npm run storybook

# Clean up local development
cd app && npm run yalc:unlink
cd typescript/design-system && npm run yalc:unpublish
```

### Publishing Commands

```bash
# Check who you are
npm whoami

# Publish dev version
npm run publish:dev

# Check published versions
npm run check-package

# Update app to latest published version
cd app && npm install @vectorshift/ui@dev

# Rollback app to specific version
cd app && npm install @vectorshift/ui@3.0.0
```

## 📞 Support

For questions or issues:

1. Check this README first
2. Look at existing components in Storybook
3. Ask the frontend team
4. Create an issue in the main repository

---

**Remember:** Always test locally with `yalc` before publishing! 🔗
