# @maldarabseh/dga-react

<p align="center">
  <img src="https://img.shields.io/npm/v/@maldarabseh/dga-react?style=flat-square" alt="npm version">
  <img src="https://img.shields.io/npm/l/@maldarabseh/dga-react?style=flat-square" alt="license">
  <img src="https://img.shields.io/badge/React-18%2B-blue?style=flat-square" alt="React 18+">
  <img src="https://img.shields.io/badge/status-under%20development-yellow?style=flat-square" alt="Status">
</p>

React components for the **DGA Design System** - A comprehensive UI component library built for the Digital Government Authority (DGA) of the Kingdom of Saudi Arabia.

## 🚧 Under Active Development

This package is under active development. We are continuously adding new components, improving existing ones, and enhancing documentation. Contributions and feedback are welcome!

## 🎯 Purpose

The DGA Design System aims to provide a unified, accessible, and RTL-ready component library that ensures consistency across government digital services. Built with **Stencil.js** for maximum compatibility, the components work seamlessly across:

- ✅ **React** (this package)
- ✅ **Angular** (`@maldarabseh/dga-angular`)
- ✅ **Vue** (coming soon)
- ✅ **Vanilla JS/HTML** (`@maldarabseh/dga-stencil`)

## 📦 Installation

```bash
npm install @maldarabseh/dga-react @maldarabseh/dga-stencil
```

## 🚀 Quick Start

### 1. Import Styles

In your `App.tsx` or `index.tsx`:

```tsx
import '@maldarabseh/dga-stencil/dist/dga/dga.css';
```

### 2. Use Components

```tsx
import { DgaButton, DgaInputText, DgaDropdown, DgaDropdownItem } from '@maldarabseh/dga-react';

function App() {
  const [email, setEmail] = useState('');
  
  return (
    <div>
      <DgaButton 
        variant="primary" 
        onDgaClick={() => alert('Clicked!')}>
        Click Me
      </DgaButton>
      
      <DgaInputText 
        label="Email"
        placeholder="Enter your email"
        helperText="We'll never share your email"
        value={email}
        onDgaInput={(e) => setEmail(e.detail)}
      />
      
      <DgaDropdown 
        label="Country" 
        placeholder="Select a country"
        onDgaChange={(e) => console.log('Selected:', e.detail)}>
        <DgaDropdownItem value="sa">Saudi Arabia</DgaDropdownItem>
        <DgaDropdownItem value="ae">UAE</DgaDropdownItem>
      </DgaDropdown>
    </div>
  );
}
```

## 📚 Available Components

| Component | Description |
|-----------|-------------|
| `DgaButton` | Button with multiple variants, sizes, and states |
| `DgaInputText` | Text input with label, helper text, validation |
| `DgaDropdown` | Select dropdown with single/multi selection |
| `DgaDropdownItem` | Dropdown option item |
| `DgaCheckbox` | Checkbox with indeterminate state support |
| `DgaRadio` | Radio button |
| `DgaSwitch` | Toggle switch |
| `DgaSlider` | Single value and range slider |
| `DgaCard` | Card with selectable/expandable variants |
| `DgaAvatar` | Avatar with image/initials support |
| `DgaAvatarGroup` | Grouped avatars with overflow |
| `DgaLink` | Styled navigation link |
| `DgaList` | List container |
| `DgaListItem` | List item |
| `DgaFloatingButton` | Floating action button (FAB) |
| `DgaAutocomplete` | Autocomplete/typeahead input |
| `DgaLabel` | Form label |
| `DgaDivider` | Visual divider |

## 🌐 RTL Support

Full Right-to-Left (RTL) support for Arabic and other RTL languages:

```tsx
function App() {
  const [isRTL, setIsRTL] = useState(false);
  
  return (
    <div dir={isRTL ? 'rtl' : 'ltr'}>
      <DgaButton onClick={() => setIsRTL(!isRTL)}>
        Toggle RTL
      </DgaButton>
      {/* All components automatically adapt to RTL */}
    </div>
  );
}
```

## 💡 TypeScript Support

Full TypeScript support with typed props and events:

```tsx
import { DgaButton } from '@maldarabseh/dga-react';

// IDE shows all available props
<DgaButton
  variant="primary"      // 'neutral' | 'primary' | 'secondary-solid' | ...
  size="md"              // 'xs' | 'sm' | 'md' | 'lg' | 'xl'
  disabled={false}
  destructive={false}
  fullWidth={false}
  onDgaClick={(e) => {}} // CustomEvent<MouseEvent>
/>
```

## 📖 Example Usage

### Button Variants

```tsx
<DgaButton variant="primary">Primary</DgaButton>
<DgaButton variant="secondary-solid">Secondary Solid</DgaButton>
<DgaButton variant="secondary-outline">Secondary Outline</DgaButton>
<DgaButton variant="subtle">Subtle</DgaButton>
<DgaButton variant="transparent">Transparent</DgaButton>
<DgaButton variant="primary" destructive>Delete</DgaButton>
```

### Form Example

```tsx
function ContactForm() {
  const [form, setForm] = useState({ name: '', email: '', country: '' });
  
  return (
    <form>
      <DgaInputText
        label="Name"
        value={form.name}
        onDgaInput={(e) => setForm({ ...form, name: e.detail })}
      />
      
      <DgaInputText
        label="Email"
        type="email"
        value={form.email}
        onDgaInput={(e) => setForm({ ...form, email: e.detail })}
      />
      
      <DgaDropdown
        label="Country"
        placeholder="Select country"
        onDgaChange={(e) => setForm({ ...form, country: e.detail })}>
        <DgaDropdownItem value="sa">Saudi Arabia</DgaDropdownItem>
        <DgaDropdownItem value="ae">UAE</DgaDropdownItem>
        <DgaDropdownItem value="eg">Egypt</DgaDropdownItem>
      </DgaDropdown>
      
      <DgaButton variant="primary" type="submit">
        Submit
      </DgaButton>
    </form>
  );
}
```

### Card Selection

```tsx
function CardGrid() {
  const [selected, setSelected] = useState<string | null>(null);
  
  const cards = [
    { id: '1', title: 'Option A', description: 'First option' },
    { id: '2', title: 'Option B', description: 'Second option' },
    { id: '3', title: 'Option C', description: 'Third option' },
  ];
  
  return (
    <div style={{ display: 'grid', gap: '16px' }}>
      {cards.map((card) => (
        <DgaCard
          key={card.id}
          type="selectable"
          cardTitle={card.title}
          description={card.description}
          selected={selected === card.id}
          onDgaSelect={() => setSelected(card.id)}
        />
      ))}
    </div>
  );
}
```

## 🎨 Styling

### Adding Arabic Font (Recommended)

In your `index.html`:

```html
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans+Arabic:wght@400;500;600;700&display=swap" rel="stylesheet">
```

### Custom Theming

Override CSS variables for custom theming:

```css
:root {
  --dga-primary-color: #00a651;
  --dga-font-family: 'IBM Plex Sans Arabic', sans-serif;
}
```

## 🔗 Related Packages

| Package | Description |
|---------|-------------|
| [@maldarabseh/dga-stencil](https://www.npmjs.com/package/@maldarabseh/dga-stencil) | Core web components |
| [@maldarabseh/dga-angular](https://www.npmjs.com/package/@maldarabseh/dga-angular) | Angular wrapper components |
| [@maldarabseh/dga-tokens](https://www.npmjs.com/package/@maldarabseh/dga-tokens) | Design tokens (SCSS, CSS, TS) |

## 🤝 Contributing

This project is under active development. We welcome:
- Bug reports
- Feature requests
- Pull requests
- Documentation improvements

## 📄 License

MIT License - see LICENSE file for details.

---

<p align="center">
  Built with ❤️ for the Digital Government Authority of Saudi Arabia
</p>