DamkarAI Components

A comprehensive React component library for DamkarAI - an AI-powered text and code assistant. This library provides a complete set of components, hooks, and utilities to build modern AI interfaces with beautiful design and smooth animations.

🚀 Installation

npm install @damkarai/components
# or
yarn add @damkarai/components
# or
pnpm add @damkarai/components

📦 Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install react@>=18.0.0 react-dom@>=18.0.0

🎯 Quick Start

import { DamkarMascot, DamkarButton, DamkarLoader } from '@damkarai/components';
import '@damkarai/components/dist/style.css';

function App() {
  return (
    <div>
      <DamkarMascot 
        variant="head" 
        service="llm" 
        state="processing" 
        size="lg" 
        animated={true} 
      />
      
      <DamkarButton 
        variant="primary" 
        onClick={() => console.log('Clicked!')}
      >
        Start Processing
      </DamkarButton>
      
      <DamkarLoader 
        service="grammar" 
        message="Checking your text..." 
        showMascot={true} 
      />
    </div>
  );
}

🧩 Core Components

DamkarMascot

The heart of the library - an animated AI mascot that represents different services and states.

<DamkarMascot 
  variant="full" | "half" | "head" | "icon"
  service="llm" | "grammar" | "code" | "text" | "idle"
  state="idle" | "processing" | "success" | "error" | "thinking"
  size="xs" | "sm" | "md" | "lg" | "xl"
  animated={true}
  message="Optional status message"
  onClick={() => {}}
/>

DamkarButton

Consistent button component with multiple variants and loading states.

<DamkarButton
  variant="primary" | "secondary" | "accent" | "warning" | "error" | "success" | "neutral"
  size="xs" | "sm" | "md" | "lg" | "xl"
  loading={false}
  disabled={false}
  icon={<SendIcon />}
  iconPosition="left" | "right"
  fullWidth={false}
  onClick={() => {}}
>
  Button Text
</DamkarButton>

DamkarLoader

Loading states with multiple variants including mascot animations.

<DamkarLoader
  service="llm" | "grammar" | "code" | "text"
  variant="spinner" | "dots" | "mascot" | "skeleton"
  message="Loading message..."
  showMascot={true}
  size="sm" | "md" | "lg"
  estimatedTime={30}
/>

DamkarStatusCard

Status notifications with mascot integration.

<DamkarStatusCard
  status="success" | "error" | "warning" | "info"
  title="Status Title"
  description="Detailed description"
  showMascot={true}
  dismissible={true}
  onDismiss={() => {}}
  action={<DamkarButton>Action</DamkarButton>}
/>

DamkarInput

Form inputs with validation and character counting.

<DamkarInput
  type="text" | "email" | "password" | "textarea"
  label="Input Label"
  placeholder="Enter text..."
  value={value}
  onChange={setValue}
  error="Error message"
  required={true}
  maxLength={500}
  rows={4} // for textarea
/>

🎨 Theming

Using the Theme Hook

import { useDamkarTheme } from '@damkarai/components';

function ThemeToggle() {
  const { theme, toggleTheme, setTheme, isDark } = useDamkarTheme();
  
  return (
    <button onClick={toggleTheme}>
      Current theme: {theme}
    </button>
  );
}

CSS Variables

The library uses CSS variables for theming. You can customize the design system:

:root {
  --damkar-primary: #0066FF;
  --damkar-secondary: #6366F1;
  --damkar-accent: #10B981;
  --damkar-warning: #F59E0B;
  --damkar-error: #EF4444;
  --damkar-success: #10B981;
  
  /* Spacing */
  --damkar-space-xs: 4px;
  --damkar-space-sm: 8px;
  --damkar-space-md: 16px;
  --damkar-space-lg: 24px;
  --damkar-space-xl: 32px;
  
  /* Typography */
  --damkar-font-family: 'Inter', sans-serif;
  --damkar-font-mono: 'JetBrains Mono', monospace;
}

Dark Mode

Dark mode is automatically supported through CSS variables and the data-theme attribute:

<div data-theme="dark">
  <DamkarMascot variant="head" />
</div>

🔧 Advanced Usage

TypeScript Support

The library is built with TypeScript and provides comprehensive type definitions:

import type { 
  DamkarMascotProps, 
  DamkarService, 
  DamkarState 
} from '@damkarai/components';

const mascotProps: DamkarMascotProps = {
  variant: 'head',
  service: 'llm',
  state: 'processing',
  size: 'lg'
};

Custom Styling

Use the cn utility for conditional classes:

import { cn } from '@damkarai/components';

<DamkarButton 
  className={cn(
    'custom-button',
    isActive && 'active-state',
    { 'special-variant': isSpecial }
  )}
>
  Custom Button
</DamkarButton>

Animation Control

Disable animations for reduced motion preference:

<DamkarMascot 
  animated={!window.matchMedia('(prefers-reduced-motion: reduce)').matches}
/>

🎭 Animation Features

Mascot Animations

• Idle: Subtle floating and glow pulse
• Processing: Service-specific animations (code syntax highlighting, text flowing, etc.)
• Success: Celebration with positive feedback
• Error: Concerned but helpful expression
• Thinking: Contemplative movement

Micro-interactions

• Button hover states with mascot acknowledgment
• Loading states with typing animations
• File upload with mascot "catching" files
• Copy/export with handover animations

♿ Accessibility

The library follows accessibility best practices:

• ARIA labels and descriptions
• Keyboard navigation support
• Screen reader compatibility
• High contrast mode support
• Reduced motion preferences
• Focus management

<DamkarButton
  aria-label="Process document with AI"
  aria-describedby="help-text"
>
  Process
</DamkarButton>

📱 Responsive Design

All components are responsive and work across different screen sizes:

<DamkarMascot 
  size={{ mobile: 'sm', tablet: 'md', desktop: 'lg' }}
/>

🧪 Testing

Components include test IDs for easy testing:

<DamkarButton testId="submit-button">
  Submit
</DamkarButton>

// In tests
const button = screen.getByTestId('submit-button');

📚 Storybook Documentation

Explore all components interactively:

npm run storybook

This opens the Storybook interface where you can:

• View all components and variants
• Test different props interactively
• See code examples
• Test accessibility features

🔧 Development

Local Development

git clone https://github.com/damkarai/components
cd components
npm install
npm run dev

Building the Library

npm run build

This creates:

• dist/index.js - UMD build
• dist/index.esm.js - ES modules build
• dist/index.d.ts - TypeScript definitions
• dist/style.css - Compiled styles

Running Tests

npm test        # Run tests
npm run test:ui # Run tests with UI

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run tests and ensure they pass
6. Submit a pull request

🔗 Links

• Documentation
• Storybook
• GitHub Repository
• NPM Package
• Issues

📈 Roadmap

Current Version (1.0.0)

• ✅ Core mascot component with animations
• ✅ Essential UI components (Button, Input, Loader, StatusCard)
• ✅ Theme system with light/dark mode
• ✅ TypeScript support
• ✅ Storybook documentation

Upcoming Features (1.1.0)

• 🔄 Chat interface component
• 🔄 Grammar checking component
• 🔄 Code assistant component
• 🔄 File upload component
• 🔄 Voice interface components

Future Versions

• 🔜 Advanced AI integrations
• 🔜 More animation variants
• 🔜 Additional theme options
• 🔜 Mobile-specific optimizations
• 🔜 SSR improvements

Built with ❤️ by the DamkarAI Team