npm package: @maldarabseh/dga-angular
Description: Angular components for DGA Design System - Ivy compiled
Author: maldarabseh
Latest version: 1.0.7

# @maldarabseh/dga-angular

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

Angular 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:

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

## 📦 Installation

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

## 🚀 Quick Start

### 1. Import Components

```typescript
import { Component } from '@angular/core';
import { DgaButton, DgaInputText, DgaDropdown } from '@maldarabseh/dga-angular';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [DgaButton, DgaInputText, DgaDropdown],
  template: `
    <dga-button variant="primary" (dgaClick)="handleClick()">
      Click Me
    </dga-button>
    
    <dga-input-text 
      label="Email" 
      placeholder="Enter your email"
      (dgaInput)="onInput($event)">
    </dga-input-text>
  `
})
export class ExampleComponent {
  handleClick() {
    console.log('Button clicked!');
  }
  
  onInput(event: CustomEvent<string>) {
    console.log('Input value:', event.detail);
  }
}
```

### 2. Add Global Styles

In your `angular.json`:

```json
{
  "styles": [
    "node_modules/@maldarabseh/dga-stencil/dist/dga/dga.css",
    "src/styles.scss"
  ]
}
```

Or import in `styles.scss`:

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

### 3. (Recommended) Add Arabic Font

In `index.html`:

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

## 📚 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 |
| `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` | Ordered/unordered lists |
| `DgaFloatingButton` | Floating action button (FAB) |
| `DgaAutocomplete` | Autocomplete/typeahead input |

## 🌐 RTL Support

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

```html
<html dir="rtl" lang="ar">
```

All components automatically adapt their layout for RTL.

## 💡 TypeScript Support

Starting from v1.0.6, this package includes full TypeScript support with Ivy compilation:

- ✅ Full IntelliSense in VS Code and other IDEs
- ✅ Type-safe props and events
- ✅ AOT (Ahead-of-Time) compilation support
- ✅ Tree-shaking optimization

## 📖 Example Usage

### Button Variants

```html
<dga-button variant="primary">Primary</dga-button>
<dga-button variant="secondary-solid">Secondary</dga-button>
<dga-button variant="secondary-outline">Outline</dga-button>
<dga-button variant="subtle">Subtle</dga-button>
<dga-button variant="transparent">Transparent</dga-button>
<dga-button variant="primary" [destructive]="true">Delete</dga-button>
```

### Form Controls

```html
<dga-input-text 
  label="Username"
  placeholder="Enter username"
  helperText="Must be unique"
  [error]="hasError"
  (dgaChange)="onUsernameChange($event)">
</dga-input-text>

<dga-dropdown 
  label="Country"
  placeholder="Select country"
  [multiple]="true">
  <dga-dropdown-item value="sa">Saudi Arabia</dga-dropdown-item>
  <dga-dropdown-item value="ae">UAE</dga-dropdown-item>
</dga-dropdown>

<dga-switch 
  label="Notifications"
  [checked]="notificationsEnabled"
  (dgaChange)="toggleNotifications($event)">
</dga-switch>
```

## 🔗 Related Packages

| Package | Description |
|---------|-------------|
| [@maldarabseh/dga-stencil](https://www.npmjs.com/package/@maldarabseh/dga-stencil) | Core web components |
| [@maldarabseh/dga-react](https://www.npmjs.com/package/@maldarabseh/dga-react) | React 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>