platformscode-new-angular/README.md

Angular wrapper library for DGA Design System components. Provides Angular bindings and integration for @platformscode/core web components.

# PlatformsCode Angular Library

[![npm version](https://badge.fury.io/js/platformscode-new-angular.svg)](https://www.npmjs.com/package/platformscode-new-angular)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)

Angular wrapper library for the DGA Design System components. This library provides Angular bindings and seamless integration for `@platformscode/core` web components, making it easy to use DGA components in Angular applications.

## 🚀 Quick Start

### Installation

Install the library and its peer dependency:

```bash
npm install platformscode-new-angular @platformscode/core@0.0.17
```

### Basic Setup

#### For Module-based Angular Apps

1. **Import the module** in your `app.module.ts`:

```typescript
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { PlatformsCodeNewAngularModule } from 'platformscode-new-angular';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    PlatformsCodeNewAngularModule  // Add this
  ],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],  // Important: Add this
  bootstrap: [AppComponent]
})
export class AppModule { }
```

2. **Use components** in your templates:

```html
<!-- app.component.html -->
<dga-button variant="primary" (click)="handleClick()">
  Click Me
</dga-button>

<dga-card variant="outlined">
  <dga-card-title>Welcome</dga-card-title>
  <dga-card-content>
    Your content here
  </dga-card-content>
</dga-card>
```

#### For Standalone Angular Apps

```typescript
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { PlatformsCodeNewAngularModule } from 'platformscode-new-angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [PlatformsCodeNewAngularModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <dga-button variant="primary">Standalone Button</dga-button>
  `
})
export class AppComponent { }
```

## 📚 Available Components

### Form Components
- `<dga-text-input>` - Text input field
- `<dga-number-input>` - Number input field  
- `<dga-textarea>` - Multi-line text area
- `<dga-checkbox>` - Checkbox input
- `<dga-radio-button>` - Radio button
- `<dga-switch>` - Toggle switch
- `<dga-slider>` - Range slider
- `<dga-dropdown>` - Select dropdown
- `<dga-datepicker>` - Date picker
- `<dga-file-upload>` - File upload
- `<dga-search-box>` - Search input
- `<dga-rating>` - Star rating

### Button Components
- `<dga-button>` - Primary button component
- `<dga-button-v2>` - Enhanced button with icons
- `<floating-button>` - Floating action button

### Layout Components
- `<dga-card>` - Card container
- `<dga-modal>` - Modal dialog
- `<dga-drawer>` - Side drawer
- `<dga-accordion>` - Collapsible content
- `<dga-tabs>` - Tab navigation
- `<dga-grid-container>` - Grid layout
- `<dga-flex>` - Flexbox layout

### Display Components
- `<dga-avatar>` - User avatar
- `<dga-chip>` - Information chips
- `<dga-tag>` - Content tags
- `<dga-icon>` - Icon display
- `<dga-metric>` - Metric display
- `<dga-table>` - Data table
- `<dga-list>` - List display

### Navigation Components
- `<dga-breadcrumbs>` - Breadcrumb navigation
- `<dga-pagination>` - Page navigation
- `<dga-menu>` - Navigation menu
- `<dga-link>` - Styled links

### Feedback Components
- `<dga-notification>` - Notification messages
- `<dga-loading>` - Loading indicators
- `<dga-progress-indicator>` - Progress bars
- `<dga-tooltip>` - Hover tooltips
- `<dga-alert>` - Alert messages

## 🎯 Usage Examples

### Login Form Example

```typescript
// login.component.ts
import { Component } from '@angular/core';

@Component({
  selector: 'app-login',
  templateUrl: './login.component.html'
})
export class LoginComponent {
  username = '';
  password = '';
  rememberMe = false;

  onLogin() {
    console.log('Login attempt:', { 
      username: this.username, 
      password: this.password 
    });
  }
}
```

```html
<!-- login.component.html -->
<dga-card variant="outlined">
  <dga-card-title>تسجيل الدخول</dga-card-title>
  <dga-card-content>
    <form (ngSubmit)="onLogin()">
      <div class="form-group">
        <dga-label>اسم المستخدم</dga-label>
        <dga-text-input 
          placeholder="أدخل اسم المستخدم"
          [value]="username"
          (input)="username = $event.target.value">
        </dga-text-input>
      </div>

      <div class="form-group">
        <dga-label>كلمة المرور</dga-label>
        <dga-text-input 
          type="password"
          placeholder="أدخل كلمة المرور"
          [value]="password"
          (input)="password = $event.target.value">
        </dga-text-input>
      </div>

      <dga-checkbox 
        [checked]="rememberMe"
        (change)="rememberMe = $event.target.checked"
        label="تذكرني">
      </dga-checkbox>

      <dga-button 
        variant="primary" 
        size="large" 
        type="submit">
        تسجيل الدخول
      </dga-button>
    </form>
  </dga-card-content>
</dga-card>
```

### Data Dashboard Example

```typescript
// dashboard.component.ts
import { Component } from '@angular/core';

@Component({
  selector: 'app-dashboard',
  templateUrl: './dashboard.component.html'
})
export class DashboardComponent {
  metrics = [
    { label: 'إجمالي المستخدمين', value: 1234, trend: 'up' },
    { label: 'المبيعات الشهرية', value: 98765, trend: 'up' },
    { label: 'معدل التحويل', value: 3.2, trend: 'down' }
  ];

  tableData = [
    { name: 'أحمد محمد', email: 'ahmed@example.com', status: 'active' },
    { name: 'فاطمة علي', email: 'fatima@example.com', status: 'pending' }
  ];
}
```

```html
<!-- dashboard.component.html -->
<div class="dashboard">
  <!-- Metrics -->
  <div class="metrics-grid">
    <dga-card *ngFor="let metric of metrics" variant="flat">
      <dga-card-content>
        <dga-metric>
          <h3>{{ metric.label }}</h3>
          <p class="metric-value">{{ metric.value }}</p>
          <dga-chip [variant]="metric.trend === 'up' ? 'success' : 'danger'">
            {{ metric.trend === 'up' ? '↗️ زيادة' : '↘️ انخفاض' }}
          </dga-chip>
        </dga-metric>
      </dga-card-content>
    </dga-card>
  </div>

  <!-- Data Table -->
  <dga-card variant="outlined">
    <dga-card-title>بيانات المستخدمين</dga-card-title>
    <dga-card-content>
      <dga-table>
        <thead>
          <tr>
            <th>الاسم</th>
            <th>البريد الإلكتروني</th>
            <th>الحالة</th>
          </tr>
        </thead>
        <tbody>
          <tr *ngFor="let user of tableData">
            <td>{{ user.name }}</td>
            <td>{{ user.email }}</td>
            <td>
              <dga-status-tag [status]="user.status">
                {{ user.status }}
              </dga-status-tag>
            </td>
          </tr>
        </tbody>
      </dga-table>
    </dga-card-content>
  </dga-card>
</div>
```

### Modal Dialog Example

```typescript
// modal-example.component.ts
import { Component } from '@angular/core';

@Component({
  selector: 'app-modal-example',
  template: `
    <dga-button variant="primary" (click)="openModal()">
      فتح النافذة المنبثقة
    </dga-button>

    <dga-modal [open]="showModal" size="medium">
      <dga-modal-header>
        <dga-modal-title>تأكيد العملية</dga-modal-title>
      </dga-modal-header>
      <dga-modal-body>
        <p>هل أنت متأكد من أنك تريد المتابعة؟</p>
      </dga-modal-body>
      <dga-modal-actions>
        <dga-button variant="secondary" (click)="closeModal()">
          إلغاء
        </dga-button>
        <dga-button variant="primary" (click)="confirmAction()">
          تأكيد
        </dga-button>
      </dga-modal-actions>
    </dga-modal>
  `
})
export class ModalExampleComponent {
  showModal = false;

  openModal() {
    this.showModal = true;
  }

  closeModal() {
    this.showModal = false;
  }

  confirmAction() {
    console.log('Action confirmed');
    this.closeModal();
  }
}
```

## ⚙️ Configuration

### Component Variants

Most components support different variants:

```html
<!-- Button variants -->
<dga-button variant="primary">Primary</dga-button>
<dga-button variant="secondary">Secondary</dga-button>
<dga-button variant="success">Success</dga-button>
<dga-button variant="danger">Danger</dga-button>
<dga-button variant="warning">Warning</dga-button>

<!-- Card variants -->
<dga-card variant="flat">Flat Card</dga-card>
<dga-card variant="outlined">Outlined Card</dga-card>
<dga-card variant="raised">Raised Card</dga-card>

<!-- Chip variants -->
<dga-chip variant="primary" text="Primary Chip"></dga-chip>
<dga-chip variant="success" text="Success Chip"></dga-chip>
```

### Component Sizes

Many components support size options:

```html
<!-- Button sizes -->
<dga-button size="small">Small</dga-button>
<dga-button size="medium">Medium</dga-button>
<dga-button size="large">Large</dga-button>

<!-- Avatar sizes -->
<dga-avatar size="small" src="avatar.jpg"></dga-avatar>
<dga-avatar size="medium" src="avatar.jpg"></dga-avatar>
<dga-avatar size="large" src="avatar.jpg"></dga-avatar>
```

## 🎨 Styling

The components come with built-in DGA Design System styling. You can customize appearance using CSS custom properties:

```css
/* Override DGA component styles */
dga-button {
  --button-primary-bg: #your-color;
  --button-primary-text: #your-text-color;
}

dga-card {
  --card-border-radius: 12px;
  --card-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}
```

## 🌍 RTL Support

The library fully supports right-to-left (RTL) languages:

```html
<div dir="rtl">
  <dga-text-input placeholder="أدخل النص هنا"></dga-text-input>
  <dga-button variant="primary">زر</dga-button>
</div>
```

## 🛠️ Event Handling

Components emit standard DOM events that you can handle in Angular:

```html
<!-- Form events -->
<dga-text-input 
  (input)="onTextChange($event)"
  (focus)="onFocus($event)"
  (blur)="onBlur($event)">
</dga-text-input>

<dga-checkbox 
  (change)="onCheckboxChange($event)">
</dga-checkbox>

<!-- Button events -->
<dga-button (click)="onClick($event)">
  Click Me
</dga-button>

<!-- Custom component events -->
<dga-datepicker (dateChange)="onDateSelected($event)">
</dga-datepicker>
```

```typescript
// Component event handlers
onTextChange(event: Event) {
  const target = event.target as HTMLInputElement;
  console.log('Text changed:', target.value);
}

onCheckboxChange(event: Event) {
  const target = event.target as HTMLInputElement;
  console.log('Checkbox changed:', target.checked);
}

onClick(event: Event) {
  console.log('Button clicked');
}
```

## 🔧 Troubleshooting

### Common Issues

**1. Components not rendering:**
```typescript
// Make sure you have CUSTOM_ELEMENTS_SCHEMA
@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]  // This is required!
})
```

**2. TypeScript errors:**
```typescript
// Add to tsconfig.json
{
  "compilerOptions": {
    "skipLibCheck": true
  }
}
```

**3. Styling issues:**
```css
/* Prevent global styles from interfering */
dga-button, dga-text-input, dga-card {
  all: revert !important;
}
```

**4. Events not working:**
```html
<!-- Use proper event binding -->
<dga-text-input 
  [value]="myValue"
  (input)="myValue = $event.target.value">
</dga-text-input>
```

### Server-Side Rendering (SSR)

For Angular Universal/SSR support:

```typescript
import { isPlatformBrowser } from '@angular/common';
import { PLATFORM_ID, Inject } from '@angular/core';

export class MyComponent {
  constructor(@Inject(PLATFORM_ID) private platformId: Object) {}

  ngOnInit() {
    if (isPlatformBrowser(this.platformId)) {
      // DGA components are available
    }
  }
}
```

## 📖 API Reference

### Common Properties

Most components support these common properties:

| Property | Type | Description |
|----------|------|-------------|
| `variant` | `string` | Component style variant |
| `size` | `string` | Component size (small, medium, large) |
| `disabled` | `boolean` | Disable the component |
| `placeholder` | `string` | Placeholder text for inputs |
| `value` | `any` | Component value |

### Common Events

| Event | Description |
|-------|-------------|
| `click` | Element clicked |
| `input` | Input value changed |
| `change` | Component value changed |
| `focus` | Element focused |
| `blur` | Element lost focus |

## 🤝 Contributing

We welcome contributions! To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📝 License

This project is licensed under the ISC License.

## 🔗 Links

- [npm Package](https://www.npmjs.com/package/platformscode-new-angular)
- [DGA Design System](https://www.npmjs.com/package/@platformscode/core)
- [GitHub Issues](https://github.com/suliman-998/platformscode-new-angular/issues)

## 📞 Support

For support and questions:

- 📧 Email: salburaym@su.edu.sa
- 🐛 Issues: [GitHub Issues](https://github.com/suliman-998/platformscode-new-angular/issues)

---

Made with ❤️ for the Angular community