npm package: @pyrick/harmonia
Description: Pyrick's UI Component Library - A suite of custom, reusable React components built with TypeScript and Tailwind CSS
Author: Pyrick Team
Latest version: 1.0.10

# Harmonia - Enterprise UI Component Library

**Pyrick's comprehensive UI component library** built with React, TypeScript, and Tailwind CSS. Harmonia provides a complete design system and 60+ production-ready components to ensure visual consistency and developer productivity across all Pyrick applications.

*Harmonia was the goddess of harmony and concord - reflecting our mission to create visual harmony and consistent user experiences.*

## Quick Start

### Installation

```bash
npm install @pyrick/harmonia
```

### Basic Usage

```tsx
import { Button, Card, ThemeProvider } from '@pyrick/harmonia';
import '@pyrick/harmonia/dist/index.css';

function App() {
  return (
    <ThemeProvider>
      <Card>
        <Button variant="default">Welcome to Harmonia</Button>
      </Card>
    </ThemeProvider>
  );
}
```

## Features

### Complete Component Library
- **60+ Components** - Forms, layouts, navigation, feedback, and data display
- **Advanced Data Tables** - Full-featured tables with sorting, filtering, and pagination
- **Toast System** - Complete notification system with state management
- **Rich Text Editor** - TipTap-based editor for content creation

### Enterprise-Ready
- **TypeScript First** - Complete type safety with comprehensive definitions
- **Accessibility Built-In** - WCAG 2.1 AA compliant components
- **Theme System** - Complete design system with light/dark mode support
- **Framework Agnostic** - Works with any React application

### Developer Experience
- **Storybook Documentation** - Interactive component playground
- **Tree Shaking** - Optimized bundle sizes
- **ESM & CommonJS** - Multiple module formats
- **Complete TypeScript Support** - Full IntelliSense and autocomplete

## Component Categories

### Forms & Inputs
- `Button`, `Input`, `Label`, `TextArea`, `Checkbox`, `Select`
- `RadioGroup`, `Switch`, `Slider`, `DatePicker`, `Calendar`
- `Form`, `Progress`, `Toggle`, `SearchableCombobox`, `Command`

### Layout & Structure
- `Card`, `Sheet`, `Collapsible`, `ScrollArea`, `Separator`
- `ResizeHandle`, `SplitPane`, `PaneHeader`, `PaneContent`

### Navigation
- `Tabs`, `DropdownMenu`, `Menubar`, `Link`, `ThemeSwitcher`
- `GlobalSearch` (with customizable search functions)

### Data Display
- `Table`, `AdvancedDataTable`, `Badge`, `Avatar`, `Carousel`
- `Chart`, `Skeleton`, `StackedCards`, `PyrickLogo`, `PyrickFullLogo`

### Feedback & Dialogs
- `Alert`, `Dialog`, `Toast`, `Toaster`, `Tooltip`, `Popover`
- `ErrorDetailsDialog` (with clipboard functionality)

### Business Components
- `RichTextField` (TipTap editor), `ConstrainedSection`, `FlexibleSection`
- `StyledCard`, `TabbedFormLayout`

## Advanced Features

### Data Tables
```tsx
import { AdvancedDataTable } from '@pyrick/harmonia';

<AdvancedDataTable
  data={users}
  columns={columns}
  enableSorting
  enableFiltering
  enablePagination
/>
```

### Toast Notifications
```tsx
import { useToast } from '@pyrick/harmonia';

function MyComponent() {
  const { toast } = useToast();
  
  return (
    <Button 
      onClick={() => toast({
        title: "Success",
        description: "Operation completed",
        variant: "success"
      })}
    >
      Show Toast
    </Button>
  );
}
```

### Theme System
```tsx
import { ThemeProvider, ThemeSwitcher } from '@pyrick/harmonia';

<ThemeProvider defaultTheme="system" enableSystem>
  <ThemeSwitcher />
  {/* Your app */}
</ThemeProvider>
```

## Documentation

- **[Getting Started](./docs/getting-started.md)** - Installation and setup
- **[Component API](./docs/components/README.md)** - Detailed component documentation
- **[Design System](./docs/design-system.md)** - Colors, typography, and tokens
- **[Accessibility](./docs/accessibility.md)** - WCAG compliance guidelines
- **[Migration Guide](./docs/migration.md)** - Upgrading and migration tips

## Build Information

- **Bundle Size**: 4.1MB (optimized with tree shaking)
- **TypeScript**: Complete type definitions included
- **CSS**: 48KB themed stylesheet
- **Peer Dependencies**: React 18+ and React DOM 18+

## Development

```bash
# Install dependencies
npm install

# Development mode
npm run dev

# Build library
npm run build

# Run Storybook
npm run storybook

# Run tests
npm test

# Type checking
npm run type-check
```

## Technical Stack

- **React 18+** with TypeScript
- **Tailwind CSS** for styling
- **Radix UI** for accessibility
- **TanStack Table** for advanced tables
- **TipTap** for rich text editing
- **next-themes** for theme management
- **Rollup** for optimized builds

## License

MIT License - see [LICENSE](./LICENSE) for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/Pyrick-Inc/Harmonia/issues)
- **Documentation**: [Component Docs](./docs/)
- **Storybook**: Run `npm run storybook` for interactive documentation

---