@venkat91/ark-ui-components/README.md

React component library built on Ark UI with TypeScript and Panda CSS

# @venkat91/ark-ui-components

Modern, accessible React component library built on Ark UI with TypeScript and Panda CSS.

## 🚀 Installation

```bash
npm install @venkat91/ark-ui-components
```

## 📦 Setup & Usage

### 1. Install the package
```bash
npm install @venkat91/ark-ui-components
```

### 2. Import the CSS styles
**⚠️ Important:** You must import the CSS styles for components to render correctly.

**In your main CSS file or app entry point:**
```css
@import '@venkat91/ark-ui-components/styles.css';
```

**Or in your JavaScript/TypeScript entry point:**
```javascript
import '@venkat91/ark-ui-components/styles.css';
```

### 3. Use the components
```tsx
import { CustomButton, CustomDialog, CustomSlider } from '@venkat91/ark-ui-components';

function App() {
  return (
    <div>
      <CustomButton variant="primary" size="md">
        Click Me
      </CustomButton>
      
      <CustomDialog 
        trigger="Open Dialog"
        title="Welcome"
        description="This is a pre-built dialog component"
      />
      
      <CustomSlider 
        label="Volume"
        min={0}
        max={100}
        defaultValue={50}
      />
    </div>
  );
}
```

## 🛠️ Available Components

| Component | Description | Key Props |
|-----------|-------------|-----------|
| `CustomButton` | Versatile button with variants, sizes, and loading states | `variant`, `size`, `loading`, `leftIcon`, `rightIcon` |
| `CustomDialog` | Modal dialogs with flexible content options | `trigger`, `title`, `description`, `content` |
| `CustomTab` | Dynamic tab interfaces with customizable items | `items`, `defaultValue`, `onValueChange` |
| `CustomSlider` | Range input with configurable min/max/step | `min`, `max`, `step`, `value`, `onValueChange` |
| `CustomPopover` | Contextual overlays with smart positioning | `trigger`, `content`, `title`, `description` |

## 📚 Component Examples

### CustomButton
```tsx
import { CustomButton } from '@venkat91/ark-ui-components';

// Basic usage
<CustomButton variant="primary">Primary Button</CustomButton>

// With icons and loading
<CustomButton 
  variant="secondary" 
  size="lg"
  loading={isLoading}
  leftIcon={<SaveIcon />}
>
  Save Changes
</CustomButton>
```

### CustomDialog
```tsx
import { CustomDialog } from '@venkat91/ark-ui-components';

// Simple dialog
<CustomDialog 
  trigger="Open Dialog"
  title="Confirmation"
  description="Are you sure you want to continue?"
/>

// Custom content
<CustomDialog 
  trigger="Custom Dialog"
  content={<MyCustomForm />}
/>
```

### CustomTab
```tsx
import { CustomTab } from '@venkat91/ark-ui-components';

const tabItems = [
  { label: "Tab 1", value: "tab1", content: <div>Content 1</div> },
  { label: "Tab 2", value: "tab2", content: <div>Content 2</div> },
];

<CustomTab 
  items={tabItems}
  defaultValue="tab1"
  onValueChange={(value) => console.log(value)}
/>
```

### CustomSlider
```tsx
import { CustomSlider } from '@venkat91/ark-ui-components';

<CustomSlider 
  label="Volume"
  min={0}
  max={100}
  step={5}
  defaultValue={50}
  onValueChange={(value) => setVolume(value)}
/>
```

### CustomPopover
```tsx
import { CustomPopover } from '@venkat91/ark-ui-components';

<CustomPopover 
  trigger="Help"
  title="Information"
  description="This feature helps you manage your settings."
/>
```

## 🎨 Styling

This library uses **Panda CSS** for styling. All components come pre-styled with:
- ✅ **Modern design** with clean aesthetics
- ✅ **Responsive behavior** across screen sizes
- ✅ **Dark mode support** (where applicable)
- ✅ **Accessible colors** meeting WCAG guidelines

## ♿ Accessibility

Built with accessibility in mind:
- ✅ **WCAG 2.1 AA compliant**
- ✅ **Full keyboard navigation**
- ✅ **Screen reader support**
- ✅ **ARIA attributes** on all interactive elements
- ✅ **Focus management** for modals and complex components

## 🔧 TypeScript Support

Fully typed with TypeScript:
```tsx
import type { CustomDialogProps, TabItem } from '@venkat91/ark-ui-components';

const dialogProps: CustomDialogProps = {
  trigger: "Open",
  title: "My Dialog"
};

const tabItems: TabItem[] = [
  { label: "Home", value: "home", content: <HomePage /> }
];
```

## 📋 Requirements

- **React**: >=18.0.0
- **Node.js**: >=18.0.0

## 🏗️ Built With

- [React](https://reactjs.org/) - UI library
- [Ark UI](https://ark-ui.com/) - Headless UI components
- [TypeScript](https://www.typescriptlang.org/) - Type safety
- [Panda CSS](https://panda-css.com/) - Styling system
- [Vite](https://vitejs.dev/) - Build tool

## 📄 License

MIT © My Ark UI Team

## 🤝 Contributing

This component library is designed for internal use but contributions are welcome! Please refer to the main repository for contribution guidelines.

---

**Happy building! 🚀**