npm package: @rhammy/architect-core
Description: A production-ready, accessible React component library with 13 components and 254 tests
Author: Architect Core Contributors
Latest version: 1.0.2

# Architect Core

<div align="center">
  <h3>A Production-Ready, Accessible React Component Library</h3>
  <p>13 beautifully crafted components with 254 passing tests</p>
  
  [![Tests](https://img.shields.io/badge/tests-254%20passing-success)](https://github.com/RahmanC/Architect-core)
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
  [![Accessibility](https://img.shields.io/badge/WCAG-2.1%20AA-green)](https://www.w3.org/WAI/WCAG21/quickref/)
  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
</div>

---

## ✨ Features

- 🎨 **13 Production-Ready Components** - Dialog, Button, Input, Dropdown, Tabs, Accordion, Tooltip, Toast, Checkbox, Radio, Select, Textarea, Switch
- ♿ **100% Accessible** - WCAG 2.1 AA compliant with full keyboard navigation
- 🎯 **TypeScript First** - Fully typed with excellent IntelliSense support
- 🧪 **Thoroughly Tested** - 254 comprehensive tests with high coverage
- 📦 **Headless & Flexible** - Bring your own styles or use our defaults
- 🎭 **Controlled & Uncontrolled** - Flexible state management
- 📱 **Responsive** - Works beautifully on all screen sizes
- 🌙 **Dark Mode Ready** - Easy to theme and customize

## 🚀 Quick Start

### Installation

```bash
npm install @rhammy/architect-core
# or
yarn add @rhammy/architect-core
# or
pnpm add @rhammy/architect-core
```

### Basic Usage

```tsx
import { Button, Dialog, Input } from '@rhammy/architect-core';

function App() {
  return (
    <div>
      <Button variant="primary" size="lg">
        Click me
      </Button>

      <Input label="Email" type="email" placeholder="Enter your email" />
    </div>
  );
}
```

## 📚 Components

### Core Components

#### Dialog

Modal dialogs with overlay, keyboard navigation, and focus trap.

```tsx
<Dialog open={isOpen} onOpenChange={setIsOpen}>
  <DialogTrigger>Open Dialog</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Welcome</DialogTitle>
      <DialogDescription>This is a dialog</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <Button onClick={() => setIsOpen(false)}>Close</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

#### Button

Versatile button component with multiple variants and sizes.

```tsx
<Button variant="primary" size="lg" disabled={false}>
  Primary Button
</Button>

<Button variant="outline" size="md" loading={true}>
  Loading...
</Button>
```

#### Input

Text input with label, error states, and prefix/suffix support.

```tsx
<Input
  label="Email"
  type="email"
  placeholder="you@example.com"
  errorMessage="Invalid email"
  invalid={hasError}
/>
```

### Navigation Components

#### Tabs

Accessible tabs with keyboard navigation.

```tsx
<Tabs defaultValue="tab1">
  <TabsList>
    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
  </TabsList>
  <TabsContent value="tab1">Content 1</TabsContent>
  <TabsContent value="tab2">Content 2</TabsContent>
</Tabs>
```

#### Accordion

Collapsible content sections.

```tsx
<Accordion type="single" collapsible>
  <AccordionItem value="item-1">
    <AccordionTrigger>Question 1</AccordionTrigger>
    <AccordionContent>Answer 1</AccordionContent>
  </AccordionItem>
</Accordion>
```

#### Dropdown

Context menus and dropdown menus.

```tsx
<Dropdown>
  <DropdownTrigger>Open Menu</DropdownTrigger>
  <DropdownContent>
    <DropdownItem onSelect={() => {}}>Item 1</DropdownItem>
    <DropdownItem onSelect={() => {}}>Item 2</DropdownItem>
  </DropdownContent>
</Dropdown>
```

### Feedback Components

#### Tooltip

Contextual information on hover/focus.

```tsx
<Tooltip>
  <TooltipTrigger>Hover me</TooltipTrigger>
  <TooltipContent placement="top">Helpful information</TooltipContent>
</Tooltip>
```

#### Toast

Notification system with multiple variants.

```tsx
function MyComponent() {
  const { success, error } = useToastNotification();

  return (
    <button onClick={() => success('Saved!', 'Changes saved successfully')}>
      Save
    </button>
  );
}

// Wrap your app
<ToastProvider>
  <App />
</ToastProvider>;
```

### Form Components

#### Checkbox

Checkbox with indeterminate state support.

```tsx
<Checkbox
  label="Accept terms"
  checked={accepted}
  onCheckedChange={setAccepted}
  indeterminate={someSelected}
/>
```

#### Radio

Radio buttons with RadioGroup.

```tsx
<RadioGroup name="plan" value={plan} onValueChange={setPlan}>
  <Radio value="free" label="Free" />
  <Radio value="pro" label="Pro" />
</RadioGroup>
```

#### Select

Dropdown select with search and multiple selection.

```tsx
<Select
  options={options}
  value={selected}
  onValueChange={setSelected}
  searchable
  multiple
/>
```

#### Textarea

Multi-line text input with auto-resize.

```tsx
<Textarea
  label="Description"
  maxLength={500}
  showCount
  autoResize
  minRows={3}
/>
```

#### Switch

Toggle switch component.

```tsx
<Switch
  label="Enable notifications"
  checked={enabled}
  onCheckedChange={setEnabled}
/>
```

## 🎨 Styling

Architect Core is a headless component library, giving you full control over styling. Components come with minimal default styles and use inline styles for essential layout.

### Custom Styling

```tsx
// Using className
<Button className="my-custom-button">
  Styled Button
</Button>

// Using style prop
<Button style={{ backgroundColor: '#0066FF', padding: '12px 24px' }}>
  Inline Styled
</Button>
```

### CSS Variables

You can define CSS variables for consistent theming:

```css
:root {
  --color-primary: #0066ff;
  --color-error: #ef4444;
  --color-success: #10b981;
  --border-radius: 6px;
}
```

## ♿ Accessibility

All components follow WAI-ARIA best practices:

- ✅ Proper ARIA attributes
- ✅ Keyboard navigation
- ✅ Focus management
- ✅ Screen reader support
- ✅ Color contrast compliance

### Keyboard Navigation

- **Dialog**: `Escape` to close, focus trap
- **Dropdown**: Arrow keys, `Enter`, `Escape`
- **Tabs**: Arrow keys, `Home`, `End`
- **Accordion**: Arrow keys, `Home`, `End`
- **Select**: Arrow keys, `Enter`, `Escape`, `Home`, `End`
- **Radio**: Arrow keys to navigate options

## 🧪 Testing

All components are thoroughly tested:

```bash
# Run all tests
npm test

# Run tests in watch mode
npm test:watch

# Generate coverage report
npm test:coverage
```

## 📖 Documentation

- **Storybook**: Run `npm run storybook` to explore components interactively
- **API Docs**: Each component is fully documented with TypeScript types
- **Examples**: Check the `stories` files for usage examples

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

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

## 📝 License

MIT © RahmanC

## 🙏 Acknowledgments

Built with:

- React
- TypeScript
- Vitest
- Storybook
- Testing Library

---

<div align="center">
  <p>Made with ❤️ by the Architect Core team</p>
  <p>
    <a href="https://github.com/RahmanC/Architect-core">GitHub</a> •
    <a href="https://github.com/RahmanC/Architect-core/issues">Issues</a> •
    <a href="https://github.com/RahmanC/Architect-core/discussions">Discussions</a>
  </p>
</div>