PlatformsCode Angular Library

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:

npm install platformscode-new-angular @platformscode/[email protected]

Basic Setup

For Module-based Angular Apps

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

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:

<!-- 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

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

// 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 
    });
  }
}

<!-- 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

// 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: '[email protected]', status: 'active' },
    { name: 'فاطمة علي', email: '[email protected]', status: 'pending' }
  ];
}

<!-- 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

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

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

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

/* 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:

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

<!-- 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>

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

// Make sure you have CUSTOM_ELEMENTS_SCHEMA
@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]  // This is required!
})

2. TypeScript errors:

// Add to tsconfig.json
{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

3. Styling issues:

/* Prevent global styles from interfering */
dga-button, dga-text-input, dga-card {
  all: revert !important;
}

4. Events not working:

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

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
• DGA Design System
• GitHub Issues

📞 Support

For support and questions:

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues

Made with ❤️ for the Angular community