@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)
- 🔤 **Local Font Support** - Beautiful Geist fonts bundled locally for offline support

## 📦 Installation

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

### Peer Dependencies

This library requires these peer dependencies:

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

## 🎯 Quick Setup

### 1. Import Styles

Import the component styles **with fonts** in your app entry point:

```tsx
// In your main App.tsx, _app.tsx, or layout.tsx
import '@anyreach/component-library-ui/styles'
```

**Alternative import paths:**

```tsx
// Both of these work identically
import '@anyreach/component-library-ui/styles'
import '@anyreach/component-library-ui/dist/style.css'
```

### 2. Configure Tailwind CSS

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

```js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './app/**/*.{js,ts,jsx,tsx}', // For Next.js app directory
    './pages/**/*.{js,ts,jsx,tsx}', // For Next.js pages directory
    './node_modules/@anyreach/component-library-ui/dist/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {
      fontFamily: {
        sans: ['Geist Sans', 'Inter', 'system-ui', 'sans-serif'],
        mono: ['Geist Mono', 'JetBrains Mono', 'monospace'],
      },
    },
  },
  plugins: [],
}
```

### 3. Framework-Specific Configuration

#### Next.js Configuration

For **Next.js 13+ (App Router)** or **Next.js 12+ (Pages Router)**, add transpilation:

```js
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@anyreach/component-library-ui'],
  experimental: {
    // Required for proper SSR support
    esmExternals: 'loose',
  },
}

module.exports = nextConfig
```

#### Vite Configuration

For **Vite** projects, no additional configuration needed! Just import and use.

#### Create React App

For **CRA** projects, use CRACO or eject to configure Tailwind CSS properly.

## 🔤 Font Support

This library includes **Geist Sans** and **Geist Mono** fonts bundled locally:

- ✅ **Offline Support** - Fonts work without internet connection
- ✅ **No External Requests** - Better privacy and performance
- ✅ **Self-Contained** - Everything bundled in the npm package
- ✅ **Optimized Loading** - WOFF2 format with fallbacks

### Font Weights Included

- **Geist Sans**: 400, 500, 600, 700 (Regular to Bold)
- **Geist Mono**: 400, 500, 600, 700 (Regular to Bold)

### Font CSS Variables

The library automatically applies these font families:

```css
body {
  font-family: 'Geist Sans', Inter, system-ui, sans-serif;
}

.font-mono {
  font-family: 'Geist Mono', 'JetBrains Mono', monospace;
}
```

## 🚀 Basic Usage

```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>
  )
}
```

## 🔧 Advanced Integration

### Server-Side Rendering (SSR)

The library is fully SSR-compatible with proper hydration:

```tsx
// ✅ Works with Next.js, Remix, SvelteKit, etc.
import { Button } from '@anyreach/component-library-ui'

export default function Page() {
  return <Button>SSR-safe button</Button>
}
```

### Dynamic Imports

For code splitting, you can dynamically import components:

```tsx
import dynamic from 'next/dynamic'

const DataTable = dynamic(
  () => import('@anyreach/component-library-ui').then(mod => ({ default: mod.DataTable })),
  { ssr: false } // Optional: disable SSR for heavy components
)
```

### Custom Theme Integration

Override CSS variables for custom theming:

```css
/* In your global CSS */
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
  /* ... other variables */
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  /* ... dark mode overrides */
}
```

## 📚 Component Categories

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

## 💡 Usage Examples

### Button with Loading State

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

function SaveForm() {
  const [loading, setLoading] = useState(false)

  return (
    <Button variant="default" loading={loading} icon={<Save />}>
      Save Changes
    </Button>
  )
}
```

### Complete Form

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

function UserForm() {
  return (
    <Card className="max-w-md">
      <CardHeader>
        <h2>User Registration</h2>
      </CardHeader>
      <CardContent className="space-y-4">
        <div>
          <Label htmlFor="email">Email</Label>
          <Input id="email" type="email" placeholder="user@example.com" />
        </div>
        <div>
          <Label htmlFor="password">Password</Label>
          <Input id="password" type="password" />
        </div>
        <Checkbox>I agree to the terms and conditions</Checkbox>
        <Button className="w-full">Create Account</Button>
      </CardContent>
    </Card>
  )
}
```

### Data Table with Full Features

```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 },
  { key: 'status', title: 'Status', sortable: true, filterable: true },
]

function UsersTable() {
  return (
    <DataTable
      data={users}
      columns={columns}
      keepSearch={true}
      keepFilters={true}
      keepPagination={true}
      keepSort={true}
      pageSize={20}
    />
  )
}
```

### Complete Page Layout

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

function AdminDashboard() {
  return (
    <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}
            showAddButton={true}
            onAdd={() => setShowUserModal(true)}
          />
        </main>
      </div>
    </div>
  )
}
```

## 🛠️ Troubleshooting

### Font Loading Issues

**Problem**: Fonts not loading or showing fallbacks

```tsx
// ❌ Wrong: CSS not imported
import { Button } from '@anyreach/component-library-ui' // Missing CSS import

// ✅ Correct: Import CSS first
import '@anyreach/component-library-ui/styles'
import { Button } from '@anyreach/component-library-ui'
```

### Next.js Build Errors

**Problem**: Module not found or SSR hydration mismatches

```js
// ✅ Add to next.config.js
module.exports = {
  transpilePackages: ['@anyreach/component-library-ui'],
  experimental: {
    esmExternals: 'loose',
  },
}
```

### Tailwind CSS Not Working

**Problem**: Component styles not applying

```js
// ✅ Add to tailwind.config.js content array
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@anyreach/component-library-ui/dist/**/*.{js,ts,jsx,tsx}', // This line is required
  ],
}
```

### TypeScript Errors

**Problem**: Module declaration not found

```bash
# ✅ Install types
npm install @types/react @types/react-dom
```

### Performance Issues

**Problem**: Large bundle size

```tsx
// ✅ Use specific imports instead of barrel imports
import { Button } from '@anyreach/component-library-ui' // Tree-shaking works automatically

// ❌ Don't worry about this - our build is optimized
import * as Components from '@anyreach/component-library-ui' // Still tree-shaken
```

## 🎨 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
- **Accessibility first**: WCAG compliant with proper ARIA attributes

## 🔧 Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build library with fonts
npm run build

# Clean build artifacts
npm run clean

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Type checking
npm run type-check

# Run all validations
npm run validate
```

### Build Process

The build process includes:

1. **TypeScript compilation** - Generates type definitions
2. **Vite bundling** - Creates ESM and CommonJS builds
3. **CSS generation** - Processes Tailwind CSS with Geist fonts
4. **Font copying** - Bundles local font files for distribution

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

### v0.3.0

- ✨ **Local Font Support** - Geist Sans & Geist Mono bundled locally
- 🚀 **Improved SSR** - Better Next.js and SSR framework compatibility
- 📦 **Optimized Build** - Smaller bundle size with tree-shaking
- 🔧 **Enhanced DX** - Better TypeScript support and error messages

### v0.2.x

- 🐛 Font loading improvements and CDN fallbacks
- 🔧 Build configuration enhancements

### v0.1.x

- 🎉 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**