npm package: @maldarabseh/dga-stencil
Description: DGA Design System - Web Components built with Stencil
Author: maldarabseh
Latest version: 1.0.7

# @maldarabseh/dga-stencil

<p align="center">
  <img src="https://img.shields.io/npm/v/@maldarabseh/dga-stencil?style=flat-square" alt="npm version">
  <img src="https://img.shields.io/npm/l/@maldarabseh/dga-stencil?style=flat-square" alt="license">
  <img src="https://img.shields.io/badge/Web%20Components-Ready-blue?style=flat-square" alt="Web Components">
  <img src="https://img.shields.io/badge/status-under%20development-yellow?style=flat-square" alt="Status">
</p>

Core Web 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 provides a unified, accessible, and RTL-ready component library that ensures consistency across government digital services. Built with **Stencil.js**, these are native Web Components that work everywhere:

- ✅ **Vanilla HTML/JS** (this package)
- ✅ **Angular** (`@maldarabseh/dga-angular`)
- ✅ **React** (`@maldarabseh/dga-react`)
- ✅ **Vue** (coming soon)
- ✅ Any framework or no framework at all

## 📦 Installation

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

## 🚀 Quick Start

### Using in HTML

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <link rel="stylesheet" href="node_modules/@maldarabseh/dga-stencil/dist/dga/dga.css">
</head>
<body>
  <dga-button variant="primary">Click Me</dga-button>
  <dga-input-text label="Email" placeholder="Enter email"></dga-input-text>
  
  <script type="module">
    import { defineCustomElements } from '@maldarabseh/dga-stencil/loader';
    defineCustomElements();
  </script>
</body>
</html>
```

### Using via CDN

```html
<script type="module" src="https://unpkg.com/@maldarabseh/dga-stencil/dist/dga/dga.esm.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@maldarabseh/dga-stencil/dist/dga/dga.css">

<dga-button variant="primary">Click Me</dga-button>
```

### Using in JavaScript

```javascript
import { defineCustomElements } from '@maldarabseh/dga-stencil/loader';
import '@maldarabseh/dga-stencil/dist/dga/dga.css';

// Register all custom elements
defineCustomElements();

// Use in your app
const button = document.createElement('dga-button');
button.variant = 'primary';
button.textContent = 'Click Me';
button.addEventListener('dgaClick', () => console.log('Clicked!'));
document.body.appendChild(button);
```

## 📚 Available Components

| Component | Description |
|-----------|-------------|
| `<dga-button>` | Button with multiple variants, sizes, and states |
| `<dga-input-text>` | Text input with label, helper text, validation |
| `<dga-dropdown>` | Select dropdown with single/multi selection |
| `<dga-dropdown-item>` | Dropdown option item |
| `<dga-checkbox>` | Checkbox with indeterminate state support |
| `<dga-radio>` | Radio button |
| `<dga-switch>` | Toggle switch |
| `<dga-slider>` | Single value and range slider |
| `<dga-card>` | Card with selectable/expandable variants |
| `<dga-avatar>` | Avatar with image/initials support |
| `<dga-avatar-group>` | Grouped avatars with overflow |
| `<dga-link>` | Styled navigation link |
| `<dga-list>` | List container |
| `<dga-list-item>` | List item |
| `<dga-floating-button>` | Floating action button (FAB) |
| `<dga-autocomplete>` | Autocomplete/typeahead input |
| `<dga-label>` | Form label |
| `<dga-divider>` | Visual divider |

## 🌐 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, including:
- Text alignment
- Icon positioning
- Checkbox/radio placement
- Dropdown arrow direction
- And more...

## 📖 Component Examples

### Button

```html
<!-- Variants -->
<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>

<!-- Sizes -->
<dga-button variant="primary" size="xs">Extra Small</dga-button>
<dga-button variant="primary" size="sm">Small</dga-button>
<dga-button variant="primary" size="md">Medium</dga-button>
<dga-button variant="primary" size="lg">Large</dga-button>
<dga-button variant="primary" size="xl">Extra Large</dga-button>

<!-- States -->
<dga-button variant="primary" disabled>Disabled</dga-button>
<dga-button variant="primary" destructive>Delete</dga-button>
```

### Input

```html
<dga-input-text 
  label="Email"
  placeholder="Enter your email"
  helper-text="We'll never share your email"
  input-style="default">
</dga-input-text>

<dga-input-text 
  label="Password"
  type="password"
  error
  helper-text="Password is required">
</dga-input-text>
```

### Dropdown

```html
<dga-dropdown label="Country" placeholder="Select a country">
  <dga-dropdown-item value="sa">Saudi Arabia</dga-dropdown-item>
  <dga-dropdown-item value="ae">UAE</dga-dropdown-item>
  <dga-dropdown-item value="eg">Egypt</dga-dropdown-item>
</dga-dropdown>
```

## 🎨 Styling

### CSS Custom Properties

Customize components using CSS variables:

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

### Arabic Font (Recommended)

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

## 🔗 Related Packages

| Package | Description |
|---------|-------------|
| [@maldarabseh/dga-angular](https://www.npmjs.com/package/@maldarabseh/dga-angular) | Angular wrapper 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>