@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

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

Quick Start

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.

<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.

<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.

<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.

<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.

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.

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.

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

# 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 file for details.