@anyreach/component-library-ui/README.md

React component library built on shadcn/ui foundation following atomic design principles

# @anyreach/component-library-ui

A comprehensive React component library built on **shadcn/ui** foundation with **restrictive design
patterns** for consistent, beautiful UIs.

## ✨ Features

- 🎨 **20+ Production-Ready Components** - Complete UI component ecosystem
- 🔒 **Restrictive Design Patterns** - Consistent styling with limited customization for design
  system coherence
- ⚡ **Built on shadcn/ui** - Leverages Radix UI primitives and modern React patterns
- 🎯 **TypeScript First** - Full type safety and excellent DX
- 🌗 **Dark Mode Ready** - All components support light/dark themes
- 📱 **Responsive Design** - Mobile-first approach with Tailwind CSS
- ♿ **Accessibility** - WCAG compliant with proper ARIA attributes
- 🎭 **Class Variance Authority** - Consistent variant management
- 📊 **Advanced Data Table** - Sorting, filtering, pagination, row selection
- 🏗️ **Page Templates** - Complete layout components (Navbar, Sidebar, Lists)

## 📦 Installation

```bash
npm install @anyreach/component-library-ui
```

### Dependencies

This library requires these peer dependencies:

```bash
npm install react react-dom
```

### CSS Setup

Import the component styles in your app:

```tsx
import '@anyreach/component-library-ui/dist/style.css'
```

### Tailwind CSS Setup

Add the component paths to your `tailwind.config.js`:

```js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@anyreach/component-library-ui/dist/**/*.{js,ts,jsx,tsx}',
  ],
  // ... rest of your config
}
```

## 🚀 Quick Start

```tsx
import { Button, Input, Card, CardHeader, CardContent } from '@anyreach/component-library-ui'

function App() {
  return (
    <Card className="w-96">
      <CardHeader>
        <h2>Welcome!</h2>
      </CardHeader>
      <CardContent className="space-y-4">
        <Input placeholder="Enter your name" />
        <Button>Get Started</Button>
      </CardContent>
    </Card>
  )
}
```

## 📚 Components

### Core Components

- **Button** - Primary, secondary, destructive, ghost variants with loading states
- **Input** - Text input with search variant and icon support
- **Label** - Form labels with proper accessibility

### Form Components

- **Checkbox** - Square checkboxes with indeterminate state
- **RadioGroup** - Radio button groups with vertical/horizontal layouts
- **Textarea** - Multi-line text input with resizing
- **Slider** - Range slider with step support

### Display Components

- **Avatar** - User avatars with fallback initials and status indicators
- **Badge** - Semantic badges with color variants
- **Progress** - Progress bars with customizable height
- **Separator** - Horizontal/vertical dividers

### Layout Components

- **Card** - Content cards with header, content, and footer slots
- **Breadcrumb** - Navigation breadcrumbs with ellipsis overflow
- **Pagination** - Page navigation with numbered links

### Interactive Components

- **Select** - Dropdown selectors with groups and sections
- **Calendar** - Date picker with range selection and dropdown navigation
- **FileInput** - Drag & drop file uploader with previews

### Overlay Components

- **Modal** - Centered dialogs with backdrop
- **Sheet** - Side panels with slide animations
- **Toast** - Notification system with variants

### Data Components

- **DataTable** - Advanced table with sorting, filtering, pagination, and row selection

### Page Template Components

- **Navbar** - Top navigation with breadcrumbs and theme toggle
- **Sidebar** - Collapsible sidebar with user menu and grouped navigation
- **ListTemplate** - Complete list page with layout switching (table/cards/horizontal)

## 🎨 Design Philosophy

This library follows **restrictive design patterns**:

- **Fixed positioning**: Button icons always left, Input icons always right
- **Limited variants**: Carefully curated options to maintain consistency
- **Zinc color palette**: Subtle, professional color scheme
- **Consistent spacing**: Standardized padding, margins, and sizing
- **Type safety**: Full TypeScript support with strict interfaces

## 💡 Usage Examples

### Button with Loading

```tsx
import { Button } from '@anyreach/component-library-ui'

;<Button variant="default" loading={isSubmitting} icon={<Save />}>
  Save Changes
</Button>
```

### Calendar with Range Selection

```tsx
import { Calendar } from '@anyreach/component-library-ui'

;<Calendar selected={dateRange} onSelect={setDateRange} keepRange={true} showDropdowns={true} />
```

### Data Table

```tsx
import { DataTable } from '@anyreach/component-library-ui'

const columns = [
  { key: 'name', title: 'Name', sortable: true, filterable: true },
  { key: 'email', title: 'Email', sortable: true },
  { key: 'role', title: 'Role', sortable: true, filterable: true },
]

;<DataTable
  data={users}
  columns={columns}
  keepSearch={true}
  keepFilters={true}
  keepPagination={true}
  keepSort={true}
/>
```

### Complete Page Layout

```tsx
import { Navbar, Sidebar, ListTemplate } from '@anyreach/component-library-ui'

;<div className="h-screen flex flex-col">
  <Navbar title="Admin Panel" breadcrumbs={breadcrumbs} showThemeToggle={true} />
  <div className="flex flex-1">
    <Sidebar groups={navigationGroups} showUserMenu={true} userInfo={currentUser} />
    <main className="flex-1 p-6">
      <ListTemplate
        title="User Management"
        data={users}
        columns={userColumns}
        layout="cards"
        onLayoutChange={setLayout}
      />
    </main>
  </div>
</div>
```

## 🎯 Component Categories

### By Priority Level

- **Priority 1**: Button, Input, Label (Essential basics)
- **Priority 2**: Checkbox, RadioGroup, Textarea, Slider (Form controls)
- **Priority 3**: Avatar, Badge, Progress, Separator (Display elements)
- **Priority 4**: Card, Breadcrumb, Pagination (Layout building blocks)
- **Priority 5**: Select, Calendar, FileInput, Modal, Sheet, Toast (Advanced interactions)
- **Priority 6**: DataTable (Complex data handling)
- **Priority 7**: Navbar, Sidebar, ListTemplate (Page templates)

### By Use Case

- **Forms**: Button, Input, Label, Checkbox, RadioGroup, Textarea, Slider
- **Navigation**: Breadcrumb, Pagination, Navbar, Sidebar
- **Data Display**: DataTable, Card, Badge, Avatar, Progress
- **User Feedback**: Toast, Modal, Sheet, Progress
- **Content Organization**: Card, Separator, ListTemplate

## 🛠️ Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build library (creates dist/ folder)
npm run build

# Clean build artifacts
npm run clean

# Run linter
npm run lint

# Fix linting issues automatically
npm run lint:fix

# Check TypeScript types
npm run type-check

# Run all validations (lint + type-check + build)
npm run validate
```

**Note**: The `dist/` folder is gitignored and built fresh in CI for each release. You can build
locally for testing, but don't commit the `dist/` folder.

### 🔒 Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality:

- **ESLint** + **Prettier** run on staged files automatically
- **TypeScript** type checking prevents type errors
- **Build validation** ensures the project compiles
- **Automatic formatting** keeps code style consistent

See [Pre-commit Guide](.github/PRE_COMMIT_GUIDE.md) for detailed documentation.

```bash
# Pre-commit hooks run automatically on git commit
git add .
git commit -m "feat: add new component"  # Hooks run here!

# Skip hooks only for emergencies (not recommended)
git commit -m "hotfix" --no-verify
```

## 🚀 CI/CD Pipeline

This package uses GitHub Actions for automated testing and publishing:

### 📝 Pull Request Testing

- Runs linting and builds on every PR
- Validates package structure and installation
- Comments on PR with build status and bundle sizes

### 📦 Automatic Publishing

- Builds package fresh in CI (dist folder not committed)
- Publishes to npm when code is merged to `main` branch
- Auto-bumps version based on conventional commit messages
- Creates GitHub releases and git tags
- Zero-touch deployment workflow

### 🔧 Setup Instructions

See [GitHub Actions Setup Guide](.github/SETUP_ACTIONS.md) for detailed configuration instructions.

### 📈 Version Bumping

Uses conventional commits for automatic version bumping:

- `feat:` → Minor version bump (0.1.0 → 0.2.0)
- `fix:` → Patch version bump (0.1.0 → 0.1.1)
- `feat!:` or `BREAKING CHANGE:` → Major version bump (0.1.0 → 1.0.0)

## 📄 License

MIT License - see LICENSE file for details.

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests for any
improvements.

## 📋 Changelog

### v1.0.0

- Initial release with 20+ components
- Complete page template system
- Advanced data table with full feature set
- Comprehensive form component collection
- Dark mode support throughout
- Full TypeScript support

---

**Built with ❤️ on shadcn/ui foundation**