@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

npm install @anyreach/component-library-ui

Peer Dependencies

This library requires these peer dependencies:

npm install react react-dom tailwindcss

🎯 Quick Setup

1. Import Styles

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

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

Alternative import paths:

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

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

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

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

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

🚀 Basic Usage

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:

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

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:

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

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

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="[email protected]" />
        </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

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

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

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

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

Tailwind CSS Not Working

Problem: Component styles not applying

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

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

Performance Issues

Problem: Large bundle size

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

# 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