npm package: @opencxh/ui-kit
Description: Theme-aware UI component library for OpenCXH platform
Author: OpenCXH Team
Latest version: 3.5.0

# @opencxh/ui-kit

A comprehensive, theme-aware UI component library for the OpenCXH platform. Built with React, TypeScript, and Tailwind CSS, this library provides a consistent design system that automatically adapts to your theme configuration.

## Features

- 🎨 **Theme-aware**: All components automatically adapt to your theme colors and settings
- 🌙 **Dark mode support**: Built-in dark mode with automatic color adjustments
- ♿ **Accessible**: WCAG compliant components with proper ARIA attributes
- 📱 **Responsive**: Mobile-first design with responsive breakpoints
- 🔧 **TypeScript**: Full TypeScript support with comprehensive type definitions
- 🎯 **Consistent**: Unified design language across all components
- ⚡ **Performance**: Optimized for performance with minimal bundle size

## Installation

```bash
npm install @opencxh/ui-kit
# or
yarn add @opencxh/ui-kit
# or
pnpm add @opencxh/ui-kit
```

## Quick Start

```tsx
import { Button, TextField, Modal } from '@opencxh/ui-kit';
import { useState } from 'react';

function App() {
  const [isModalOpen, setIsModalOpen] = useState(false);

  return (
    <div>
      <TextField
        label="Email"
        placeholder="Enter your email"
        type="email"
      />
      
      <Button onClick={() => setIsModalOpen(true)}>
        Open Modal
      </Button>
      
      <Modal
        open={isModalOpen}
        onClose={() => setIsModalOpen(false)}
        title="Welcome"
      >
        <p>Hello from the UI kit!</p>
      </Modal>
    </div>
  );
}
```

## Components

### Action Components

#### Button
A versatile button component with multiple variants and states.

```tsx
<Button variant="primary" size="md">
  Primary Button
</Button>

<Button variant="outline" leftIcon={<PlusIcon />}>
  Add Item
</Button>

<Button loading variant="secondary">
  Loading...
</Button>
```

**Props:**
- `variant`: 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive'
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
- `fullWidth`: boolean
- `loading`: boolean
- `leftIcon`, `rightIcon`: React.ReactNode
- `iconOnly`: boolean

### Input Components

#### TextField
A comprehensive text input with validation states and icons.

```tsx
<TextField
  label="Search"
  placeholder="Search..."
  startIcon={<SearchIcon />}
/>

<TextField
  label="Password"
  type="password"
  error="Password is required"
/>
```

**Props:**
- `label`: string
- `helperText`: string
- `error`: string
- `size`: 'sm' | 'md' | 'lg'
- `fullWidth`: boolean
- `startIcon`, `endIcon`: React.ReactNode
- `loading`: boolean

### Overlay Components

#### Modal
An accessible modal dialog with focus management.

```tsx
<Modal
  open={isOpen}
  onClose={() => setIsOpen(false)}
  title="Settings"
  size="lg"
  footer={
    <div className="flex justify-end space-x-2">
      <Button variant="outline" onClick={() => setIsOpen(false)}>
        Cancel
      </Button>
      <Button onClick={handleSave}>
        Save
      </Button>
    </div>
  }
>
  <SettingsForm />
</Modal>
```

**Props:**
- `open`: boolean
- `onClose`: () => void
- `title`: string
- `size`: 'sm' | 'md' | 'lg' | 'xl' | 'full'
- `closeOnBackdropClick`: boolean
- `closeOnEscape`: boolean
- `footer`: React.ReactNode

### Primitive Components

#### Box
A flexible container component for layout and styling.

```tsx
<Box padding="md" background="primary" radius="lg">
  Content
</Box>

<Box as="section" padding="lg" shadow="md">
  <h2>Section Title</h2>
  <p>Section content</p>
</Box>
```

**Props:**
- `as`: keyof JSX.IntrinsicElements
- `padding`, `margin`: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
- `background`: 'none' | 'primary' | 'secondary' | 'accent' | 'success' | 'warning' | 'error' | 'info' | 'neutral'
- `radius`: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full'
- `shadow`: 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
- `border`: 'none' | 'sm' | 'md' | 'lg'
- `borderColor`: theme color names

## Theme Integration

The UI kit automatically integrates with the OpenCXH theme system. Components use CSS custom properties that are automatically generated from your theme configuration.

```tsx
import { initializeTheming } from '@opencxh/ui-kit';

// Initialize with your theme
initializeTheming({
  colors: {
    primary: '#3b82f6',
    secondary: '#6b7280',
    // ... other colors
  },
  components: {
    button: {
      radius: '0.5rem',
      shadow: '0 4px 6px -1px rgb(0 0 0 / 0.1)'
    }
  }
});
```

## Utilities

### cn
A utility function for combining class names.

```tsx
import { cn } from '@opencxh/ui-kit';

const className = cn(
  'base-class',
  condition && 'conditional-class',
  { 'object-class': true }
);
```

### useThemeVariables
A hook that provides theme-aware CSS variables and utilities.

```tsx
import { useThemeVariables } from '@opencxh/ui-kit';

function MyComponent() {
  const { colors, getBgClass, getTextClass } = useThemeVariables();
  
  return (
    <div className={getBgClass('primary', 50)}>
      <span className={getTextClass('primary', 900)}>
        Themed content
      </span>
    </div>
  );
}
```

## Development

```bash
# Install dependencies
pnpm install

# Build the library
pnpm build

# Run in development mode
pnpm dev

# Run tests
pnpm test

# Type check
pnpm type-check
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

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