@maldarabseh/dga-react

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

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

🚀 Quick Start

1. Import Styles

In your App.tsx or index.tsx:

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

2. Use Components

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:

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:

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

<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

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

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:

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

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

🔗 Related Packages

| Package | Description | |---------|-------------| | @maldarabseh/dga-stencil | Core web components | | @maldarabseh/dga-angular | Angular wrapper components | | @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.