npm package: @private-ai-ui/ui
Description: Private AI Starter UI Component Library
Author: KripZa
Latest version: 1.0.1

# @private-ai-ui/ui

A modern, accessible UI component library built with React, TypeScript, and Tailwind CSS. Designed for private AI applications with full customization support.

## Installation

```bash
# Using npm
npm install @private-ai-ui/ui

# Using yarn
yarn add @private-ai-ui/ui

# Using pnpm
pnpm add @private-ai-ui/ui
```

## Peer Dependencies

This package requires the following peer dependencies:

```json
{
  "react": "^18.0.0",
  "react-dom": "^18.0.0"
}
```

## Theme Setup

### 1. Install Tailwind CSS

If you haven't already, install Tailwind CSS:

```bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
```

### 2. Configure Tailwind

Update your `tailwind.config.js` to include the component library styles:

```javascript
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@private-ai-ui/ui/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

### 3. Import Styles

Add the component library styles to your main CSS file (e.g., `globals.css` or `index.css`):

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Your custom styles */
```

### 4. Create a Theme Provider (Optional)

For consistent theming across your app:

```tsx
// src/components/ThemeProvider.tsx
'use client';

import React from 'react';

type Theme = 'light' | 'dark';

interface ThemeContextType {
  theme: Theme;
  toggleTheme: () => void;
}

const ThemeContext = React.createContext<ThemeContextType | undefined>(undefined);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = React.useState<Theme>('dark');

  const toggleTheme = () => {
    setTheme((prev) => (prev === 'light' ? 'dark' : 'light'));
  };

  React.useEffect(() => {
    document.documentElement.classList.remove('light', 'dark');
    document.documentElement.classList.add(theme);
  }, [theme]);

  return <ThemeContext.Provider value={{ theme, toggleTheme }}>{children}</ThemeContext.Provider>;
}

export function useTheme() {
  const context = React.useContext(ThemeContext);
  if (!context) {
    throw new Error('useTheme must be used within ThemeProvider');
  }
  return context;
}
```

## Usage

### Basic Example

```tsx
import { Button, Card } from '@private-ai-ui/ui';

export default function App() {
  return (
    <div className="p-4">
      <Card className="p-6">
        <h1 className="text-2xl font-bold mb-4">Welcome to @private-ai-ui/ui</h1>
        <Button variant="default">Get Started</Button>
      </Card>
    </div>
  );
}
```

### With Variants

```tsx
import { Button } from '@private-ai-ui/ui';

export default function ButtonExamples() {
  return (
    <div className="flex gap-2">
      <Button variant="default">Default</Button>
      <Button variant="destructive">Delete</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="link">Link</Button>
    </div>
  );
}
```

### With Sizes

```tsx
import { Button } from '@private-ai-ui/ui';

export default function SizeExamples() {
  return (
    <div className="flex items-center gap-2">
      <Button size="sm">Small</Button>
      <Button size="default">Default</Button>
      <Button size="lg">Large</Button>
    </div>
  );
}
```

## Component Catalog

### Buttons

Interactive button components with various styles, sizes, and states.

- **Button** - Primary button with variants (primary, secondary, outline, ghost)
- **IconButton** - Icon-only button for compact actions
- **ButtonGroup** - Grouped buttons with connected states

```tsx
import { Button, IconButton, ButtonGroup } from '@private-ai-ui/ui';

<Button variant="primary" size="md">Click me</Button>
<IconButton icon={<Star />} size="sm" />
<ButtonGroup>
  <Button variant="primary">Save</Button>
  <Button variant="secondary">Cancel</Button>
</ButtonGroup>
```

### Inputs

Form input components for user data entry.

- **Input** - Text input field with type variants
- **TextArea** - Multi-line text input
- **Checkbox** - Boolean toggle input
- **Radio** - Single choice selection
- **Switch** - Toggle switch input
- **Select** - Dropdown selection

```tsx
import { Input, TextArea, Checkbox, Switch, Select } from '@private-ai-ui/ui';

<Input type="email" placeholder="Enter your email" />
<TextArea placeholder="Message" rows={4} />
<Checkbox label="Remember me" />
<Switch label="Enable notifications" />
<Select>
  <option>Option 1</option>
  <option>Option 2</option>
</Select>
```

### Cards

Versatile card components for content organization.

- **Card** - Basic card with variants (elevated, outlined, filled)
- **ContentCard** - Card with image and content sections
- **ProfileCard** - User profile card with avatar
- **MetricCard** - Data display card with value and trend

```tsx
import { Card, MetricCard } from '@private-ai-ui/ui';

<Card variant="elevated" padding="lg">
  <h3 className="text-lg font-semibold">Card Title</h3>
  <p>Card content here</p>
</Card>

<MetricCard
  title="Total Users"
  value="1,234"
  change="+12%"
  trend="up"
/>
```

### Typography

Text and heading components for content structure.

- **Heading** - Semantic h1-h6 with size and weight options
- **Text** - Paragraph and inline text with alignment and leading
- **Badge** - Status and category indicators
- **Label** - Form labels with required indicators
- **Code** - Inline code snippets

```tsx
import { Heading, Text, Badge, Label, Code } from '@private-ai-ui/ui';

<Heading level={1} size="4xl">Page Title</Heading>
<Text size="lg" leading="relaxed">Body text content</Text>
<Badge variant="success">Active</Badge>
<Label htmlFor="email" required>Email</Label>
<Code>npm install @private-ai-ui/ui</Code>
```

### Images

Image and avatar components.

- **Avatar** - User avatar with fallback initials and status
- **AvatarGroup** - Grouped avatars with overlap
- **Image** - Responsive image with loading states
- **Gallery** - Responsive image grid

```tsx
import { Avatar, AvatarGroup, Image, Gallery } from '@private-ai-ui/ui';

<Avatar src="photo.jpg" alt="User" status="online" />
<AvatarGroup max={3}>
  <Avatar src="user1.jpg" />
  <Avatar src="user2.jpg" />
</AvatarGroup>
<Gallery columns={3} gap="md">
  <Image src="img1.jpg" alt="Image 1" />
  <Image src="img2.jpg" alt="Image 2" />
</Gallery>
```

### Backgrounds

Decorative background components.

- **GradientBackground** - Linear gradient with animation support
- **GlowBackground** - Radial glow effects
- **PatternBackground** - Dot and grid patterns

```tsx
import { GradientBackground, GlowBackground, PatternBackground } from '@private-ai-ui/ui';

<GradientBackground from="indigo-500" to="purple-600" animated>
  <h1>Hero Content</h1>
</GradientBackground>

<GlowBackground color="primary" intensity={60}>
  <div>Content with glow</div>
</GlowBackground>

<PatternBackground pattern="dots">
  <div>Content with pattern</div>
</PatternBackground>
```

### Feedback

User feedback and loading components.

- **Alert** - Informational messages with variants (info, success, warning, danger)
- **Toast** - Temporary notifications
- **Progress** - Linear and circular progress indicators
- **Skeleton** - Loading placeholders (rect, circle, text)

```tsx
import { Alert, Toast, Progress, Skeleton } from '@private-ai-ui/ui';

<Alert variant="success" title="Success" dismissible>
  Changes saved successfully
</Alert>

<Progress value={65} label="Loading..." />
<Skeleton variant="rect" width={200} height={20} />
<Skeleton variant="circle" width={40} height={40} />
```

### Navigation

Navigation and routing components.

- **Tabs** - Tabbed interface with keyboard support
- **Pagination** - Page navigation with ellipsis
- **Breadcrumb** - Hierarchical navigation with separators

```tsx
import { Tabs, Pagination, Breadcrumb } from '@private-ai-ui/ui';

<Tabs defaultValue="tab1">
  <Tabs.List>
    <Tabs.Trigger value="tab1">Tab 1</Tabs.Trigger>
    <Tabs.Trigger value="tab2">Tab 2</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="tab1">Content 1</Tabs.Content>
  <Tabs.Content value="tab2">Content 2</Tabs.Content>
</Tabs>

<Pagination
  currentPage={1}
  totalPages={10}
  onPageChange={(page) => console.log(page)}
/>

<Breadcrumb
  items={[
    { label: 'Home', href: '/' },
    { label: 'Products', href: '/products' },
    { label: 'Category' }
  ]}
/>
```

### Layout

Structural layout components.

- **Container** - Centered content with max-width
- **Grid** - Responsive grid system
- **Stack** - Flexbox spacing wrapper (vertical/horizontal)
- **Divider** - Horizontal/vertical separators

```tsx
import { Container, Grid, Stack, Divider } from '@private-ai-ui/ui';

<Container maxWidth="xl" padding="md">
  <Stack spacing="lg">
    <header>Header</header>
    <Divider />
    <Grid cols={{ md: 2, lg: 3 }} gap="md">
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
    </Grid>
  </Stack>
</Container>;
```

### Overlay

Floating overlay components.

- **Modal** - Dialog with portal rendering and focus trap
- **Drawer** - Slide-out panel (left/right/top/bottom)
- **Popover** - Floating content container
- **Tooltip** - Contextual help text with delays

```tsx
import { Modal, Drawer, Popover, Tooltip } from '@private-ai-ui/ui';

<Modal open={isOpen} onClose={() => setIsOpen(false)} title="Dialog">
  <p>Modal content</p>
</Modal>

<Drawer open={isOpen} onClose={() => setIsOpen(false)} position="right">
  <Drawer.Header title="Settings" />
  <Drawer.Body>Settings content</Drawer.Body>
</Drawer>

<Tooltip content="Help text">
  <button>Hover me</button>
</Tooltip>
```

## Development

### Build the Library

```bash
npm run build
```

### Watch Mode

```bash
npm run dev
```

### Type Checking

```bash
npm run type-check
```

### Linting

```bash
npm run lint
```

## Features

- TypeScript support with full type definitions
- Tailwind CSS styling with full customization
- Accessible components (ARIA compliant)
- Tree-shakeable for optimal bundle size
- Zero runtime CSS-in-JS overhead
- Dark mode support
- Responsive design out of the box

## Customization

All components use Tailwind CSS utility classes, making them fully customizable. You can:

1. Extend your Tailwind config to match your brand
2. Use className prop to add custom styles
3. Create variant combinations using the component API

## License

MIT (c) KripZa (Pty) Ltd

## Support

For issues, questions, or contributions, please visit our GitHub repository.