@waaelg/dga-design-system 0.4.2

package/docs/components/accordion.md

@@ -0,0 +1,114 @@
+# Accordion
+
+Expandable sections for FAQs and grouped content.
+
+**Source:** `src/styles/components/accordion.scss`, `src/scripts/accordion.js`, `src/scripts/dga-accordion.js`  
+**Demo:** `index.html`  
+**JavaScript:** Optional — web component or `DGAAccordion` class
+
+---
+
+## Option 1: Web component (recommended)
+
+```html
+<dga-accordion>
+  <dga-accordion-item title="What is an accordion?">
+    An accordion lets users expand and collapse sections of content.
+  </dga-accordion-item>
+  <dga-accordion-item title="How do I use it?" size="lg" open>
+    Import the package once — no manual JS init required.
+  </dga-accordion-item>
+</dga-accordion>
+```
+
+### `dga-accordion-item` attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `title` | — | Header label |
+| `size` | `md` | `sm`, `md`, or `lg` |
+| `open` | — | Present = expanded on load |
+
+---
+
+## Option 2: Legacy markup + DGAAccordion
+
+```html
+<div class="dga-acc" id="myAccordion">
+  <div class="dga-acc-item">
+    <button class="dga-acc-header" aria-expanded="false">
+      <span>What is an accordion?</span>
+    </button>
+    <div class="dga-acc-content">
+      <div class="dga-acc-body">
+        An accordion lets users expand and collapse sections of content.
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+```js
+import { DGAAccordion } from '@waaelg/dga-design-on-sass'
+new DGAAccordion(document.getElementById('myAccordion'))
+```
+
+---
+
+## HTML structure (legacy)
+
+| Element | Class |
+|---------|-------|
+| Root | `dga-acc` |
+| Item | `dga-acc-item` |
+| Header (button) | `dga-acc-header` |
+| Content wrapper | `dga-acc-content` |
+| Body | `dga-acc-body` |
+
+Open state: `dga-acc-item--active` on the item (added by JS).
+
+---
+
+## Header sizes
+
+| Attribute | Height |
+|-----------|--------|
+| `data-size="sm"` | 40px |
+| `data-size="md"` | 48px (default) |
+| `data-size="lg"` | 56px |
+
+```html
+<button class="dga-acc-header" data-size="lg" aria-expanded="false">Large header</button>
+```
+
+Web component: `size="lg"` on `<dga-accordion-item>`.
+
+---
+
+## Behavior
+
+- Click header to toggle
+- Keyboard: Enter / Space on focused header
+- Sets `aria-expanded` on the header
+- Multiple panels can be open at once
+
+---
+
+## RTL
+
+Chevron icon flips automatically in RTL. Optional: `dir="rtl"` on header.
+
+---
+
+## Accessibility
+
+- Use `<button>` for headers, not `<div>`
+- Set `aria-expanded="true"` / `"false"`
+- Web component handles this automatically
+
+---
+
+## Related
+
+- [Web Components](../getting-started/web-components.md)
+- [JavaScript API](../getting-started/javascript-api.md)

package/docs/components/alert.md

@@ -0,0 +1,130 @@
+# Alert
+
+Feedback messages for success, warning, error, info, and neutral states.
+
+**Source:** `src/styles/components/alert.scss`, `src/scripts/alert.js`, `src/scripts/dga-alert.js`  
+**Demo:** `alerts.html`  
+**JavaScript:** Optional — web component or `DGAAlert` class
+
+---
+
+## Option 1: Web component (recommended)
+
+Import the package once — registers `<dga-alert>` automatically:
+
+```html
+<dga-alert variant="success-color" title="Success" dismissible>
+  When successful actions need direct feedback, show it here.
+</dga-alert>
+```
+
+### Attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `variant` | `info-color` | Alert theme (see variants below) |
+| `title` | — | Optional heading |
+| `dismissible` | — | Present = show close button |
+
+```html
+<dga-alert variant="info-white">
+  Informational message without dismiss.
+</dga-alert>
+```
+
+Dismiss fires `dga-alert-dismiss` on the element. No `new DGAAlert()` required.
+
+Works in plain HTML, ASP.NET `.cshtml`, and SPA frameworks — see [Web Components](../getting-started/web-components.md).
+
+---
+
+## Option 2: Legacy markup + DGAAlert
+
+Alerts are **HTML + CSS**. Initialize `DGAAlert` once to handle close buttons.
+
+```html
+<div class="dga-alert" data-variant="success-color">
+  <span class="dga-alert-icon" aria-hidden="true"></span>
+  <div class="dga-alert-content">
+    <h4 class="dga-alert-title">نجاح</h4>
+    <div class="dga-alert-body">تمت العملية بنجاح!</div>
+  </div>
+  <button class="dga-alert-close" type="button" data-alert-close aria-label="إغلاق">×</button>
+</div>
+```
+
+```js
+import { DGAAlert } from '@waaelg/dga-design-on-sass'
+new DGAAlert()
+```
+
+---
+
+## HTML structure (legacy)
+
+| Element | Class | Required |
+|---------|-------|----------|
+| Root | `dga-alert` | Yes |
+| Icon | `dga-alert-icon` | Recommended |
+| Content wrapper | `dga-alert-content` | Yes |
+| Title | `dga-alert-title` | Optional |
+| Body | `dga-alert-body` | Yes |
+| Close button | `dga-alert-close` + `data-alert-close` | Optional |
+
+Set variant on the root: `data-variant="success-color"` (legacy) or `variant="success-color"` (web component).
+
+---
+
+## Variants
+
+Two themes: **color** (filled accent) and **white** (light background).
+
+| Value | Status |
+|-------|--------|
+| `success-color` | Success (color theme) |
+| `success-white` | Success (white theme) |
+| `warning-color` | Warning (color) |
+| `warning-white` | Warning (white) |
+| `destructive-color` | Error / destructive (color) |
+| `destructive-white` | Error / destructive (white) |
+| `info-color` | Info (color) |
+| `info-white` | Info (white) |
+| `neutral-color` | Neutral (color) |
+| `neutral-white` | Neutral (white) |
+
+Use **color** variants on light pages; **white** variants on dense or colored backgrounds.
+
+---
+
+## JavaScript (legacy)
+
+### Vanilla
+
+```js
+import '@waaelg/dga-design-on-sass/style.css'
+import { DGAAlert } from '@waaelg/dga-design-on-sass'
+
+const alert = new DGAAlert()
+// alert.destroy() when removing listener
+```
+
+Listens for clicks on `[data-alert-close]` and hides the parent `.dga-alert`.
+
+For new projects, prefer `<dga-alert>` instead — see [Web Components](../getting-started/web-components.md).
+
+---
+
+## Accessibility
+
+- Close button: `aria-label` (e.g. "Dismiss alert" / "إغلاق")
+- Icon: `aria-hidden="true"` (decorative)
+- Use clear title + body text
+- Do not rely on color alone — title conveys status
+
+---
+
+## Related
+
+- [Web Components](../getting-started/web-components.md)
+- [JavaScript API](../getting-started/javascript-api.md)
+- [Colors](../foundations/colors.md)

package/docs/components/avatar.md

@@ -0,0 +1,74 @@
+# Avatar
+
+User profile images in circular or square shapes.
+
+**Source:** `src/styles/components/avatar.scss`  
+**Demo:** _not in index.html yet_  
+**JavaScript required:** No
+
+> **Note:** Avatar is included in the build as of the next release. Rebuild with `npm run build` after pulling latest source.
+
+---
+
+## HTML
+
+```html
+<div class="dga-avatar" data-size="md">
+  <img src="user.jpg" alt="User name" />
+</div>
+```
+
+---
+
+## Sizes
+
+| `data-size` | Dimensions |
+|-------------|------------|
+| `xs` | 24px |
+| `sm` | 32px |
+| `md` | 40px |
+| `lg` | 48px |
+| `xl` | 64px |
+| `2xl` | 80px |
+| `3xl` | 120px |
+
+```html
+<div class="dga-avatar" data-size="lg">
+  <img src="avatar.png" alt="" />
+</div>
+```
+
+---
+
+## Shape
+
+| Attribute | Shape |
+|-----------|-------|
+| (default) / `data-square="false"` | Circle |
+| `data-square="true"` | Rounded square (4px radius) |
+
+```html
+<div class="dga-avatar" data-size="md" data-square="true">
+  <img src="logo.png" alt="Organization" />
+</div>
+```
+
+---
+
+## Styling
+
+- White 2px border
+- `object-fit: cover` on images
+- `overflow: hidden`
+
+---
+
+## Enable in build
+
+Avatar is imported in `src/styles/main.scss`. Run `npm run build` to include styles in `dist/style.css`.
+
+---
+
+## Related
+
+- [Card](./card.md)

package/docs/components/breadcrumb.md

@@ -0,0 +1,56 @@
+# Breadcrumb
+
+Navigation trail showing the current page hierarchy.
+
+**Source:** `src/styles/components/breadcrumb.scss`  
+**Demo:** `index.html`  
+**JavaScript required:** No
+
+---
+
+## HTML
+
+```html
+<div class="dga-breadcrumb">
+  <a class="dga-breadcrumb-item" href="/">Home</a>
+  <a class="dga-breadcrumb-item" href="/about">About</a>
+  <a class="dga-breadcrumb-item" href="/vision" data-current="true">Our vision</a>
+</div>
+```
+
+---
+
+## Classes
+
+| Class | Purpose |
+|-------|---------|
+| `dga-breadcrumb` | Flex container |
+| `dga-breadcrumb-item` | Each crumb link |
+| `data-current="true"` | Current (last) item — muted color |
+
+---
+
+## RTL
+
+Separator chevron flips automatically when `dir="rtl"` is on a parent:
+
+```html
+<div class="dga-breadcrumb" dir="rtl">
+  <a class="dga-breadcrumb-item" href="#">الرئيسية</a>
+  <a class="dga-breadcrumb-item" data-current="true">رؤيتنا</a>
+</div>
+```
+
+---
+
+## Accessibility
+
+- Use `<nav aria-label="Breadcrumb">` wrapper in production
+- Current page: `aria-current="page"` on the last link
+- Ensure links are keyboard focusable
+
+---
+
+## Related
+
+- [Link](./link.md)

package/docs/components/button.md

@@ -0,0 +1,163 @@
+# Button
+
+Primary action component for the DGA design system.
+
+**Source:** `src/styles/components/button.scss`  
+**Demo:** `index.html` (Buttons section)  
+**JavaScript required:** No
+
+---
+
+## Overview
+
+Buttons use the base class `dga-btn` plus a variant and optional size modifier.
+
+```html
+<button class="dga-btn dga-btn-primary dga-btn-md">الاجراء الرئيسي</button>
+```
+
+---
+
+## Base class
+
+| Class | Required |
+|-------|----------|
+| `dga-btn` | Yes |
+
+Always use a `<button>` element (or `<a>` styled as button for navigation).
+
+---
+
+## Variants
+
+| Class | Use case |
+|-------|----------|
+| `dga-btn-primary` | Main action (Saudi green) |
+| `dga-btn-primary-outline` | Secondary emphasis, outline |
+| `dga-btn-neutral` | Dark neutral action |
+| `dga-btn-secondary-solid` | Secondary filled |
+| `dga-btn-secondary-outline` | Secondary outline |
+| `dga-btn-subtle` | Low emphasis |
+| `dga-btn-transparent` | Minimal, on colored backgrounds |
+| `dga-btn-ghost` | Ghost style (green text) |
+| `dga-btn-destructive` | Delete / dangerous actions |
+| `dga-btn-destructive-outline` | Destructive outline |
+| `dga-btn-success` | Success action |
+| `dga-btn-warning` | Warning action |
+| `dga-btn-info` | Info action |
+
+```html
+<button class="dga-btn dga-btn-primary">Primary</button>
+<button class="dga-btn dga-btn-secondary-outline">Secondary outline</button>
+<button class="dga-btn dga-btn-destructive">Delete</button>
+```
+
+---
+
+## Sizes
+
+| Class | Height | Font size |
+|-------|--------|-----------|
+| `dga-btn-sm` | 24px | 12px |
+| `dga-btn-md` | 32px | 14px (default) |
+| `dga-btn-lg` | 40px | 16px |
+
+If no size class is set, **medium** (`md`) applies.
+
+```html
+<button class="dga-btn dga-btn-primary dga-btn-sm">Small</button>
+<button class="dga-btn dga-btn-primary dga-btn-lg">Large</button>
+```
+
+---
+
+## Icons
+
+| Class | Purpose |
+|-------|---------|
+| `dga-btn__icon` | Icon inside button |
+| `dga-btn-icon-only` | Icon-only button (square) |
+| `dga-btn-icon-left` | Icon on left (LTR) |
+| `dga-btn-icon-right` | Icon on right (LTR) |
+
+```html
+<!-- Text + icon -->
+<button class="dga-btn dga-btn-primary dga-btn-md">
+  الاجراء الرئيسي
+  <img class="dga-btn__icon" src="arrow.svg" alt="" />
+</button>
+
+<!-- Icon only -->
+<button class="dga-btn dga-btn-primary dga-btn-md dga-btn-icon-only" aria-label="Next">
+  <img class="dga-btn__icon" src="arrow.svg" alt="" />
+</button>
+```
+
+Always provide `aria-label` on icon-only buttons.
+
+---
+
+## Modifiers
+
+| Class | Effect |
+|-------|--------|
+| `dga-btn-block` | Full width |
+| `dga-btn-pill` | Pill border radius |
+| `dga-btn-disabled` | Disabled style |
+| `disabled` attribute | Native disabled state |
+
+```html
+<button class="dga-btn dga-btn-primary dga-btn-block" disabled>Full width</button>
+```
+
+---
+
+## Button groups
+
+```html
+<div class="dga-btn-group">
+  <button class="dga-btn dga-btn-secondary-outline">Left</button>
+  <button class="dga-btn dga-btn-secondary-outline">Right</button>
+</div>
+```
+
+---
+
+## Full example
+
+```html
+<div class="dga-d-flex dga-flex-col dga-gap-3 dga-align-items-start">
+  <button class="dga-btn dga-btn-primary dga-btn-md">
+    الاجراء الرئيسي
+    <img class="dga-btn__icon" src="arrow_left.svg" alt="" />
+  </button>
+  <button class="dga-btn dga-btn-neutral dga-btn-md">Neutral</button>
+  <button class="dga-btn dga-btn-subtle dga-btn-md">اجراء دقيق</button>
+</div>
+```
+
+---
+
+## Accessibility
+
+- Use `<button type="button">` for actions, `type="submit"` for forms.
+- Icon-only buttons need `aria-label`.
+- Disabled buttons: `disabled` attribute or `dga-btn-disabled`.
+- Focus styles are built in (`:focus-visible`).
+
+---
+
+## Do / Don't
+
+| Do | Don't |
+|----|-------|
+| `dga-btn dga-btn-primary dga-btn-md` | `dga-btn-large` (invalid — use `dga-btn-lg`) |
+| `<button class="dga-btn">` | `<div class="dga-btn">` |
+| `aria-label` on icon-only | Icon-only without label |
+
+---
+
+## Related
+
+- [Colors](../foundations/colors.md)
+- [Spacing](../foundations/spacing.md)

package/docs/components/card.md

@@ -0,0 +1,78 @@
+# Card
+
+Container for grouped content with optional icon and footer.
+
+**Source:** `src/styles/components/card.scss`  
+**Demo:** `index.html`  
+**JavaScript required:** No
+
+---
+
+## Basic card
+
+```html
+<div class="dga-card">
+  <div class="dga-card-icon">
+    <img src="icon.svg" alt="" />
+  </div>
+  <div class="dga-card-content">
+    <h3 class="dga-card-title">عنوان</h3>
+    <div class="dga-card-body">
+      <p>نص المحتوى الخاص بالكارد</p>
+    </div>
+  </div>
+</div>
+```
+
+---
+
+## Structure
+
+| Element | Class | Required |
+|---------|-------|----------|
+| Root | `dga-card` | Yes |
+| Icon area | `dga-card-icon` | Optional |
+| Content | `dga-card-content` | Yes |
+| Title | `dga-card-title` | Optional |
+| Body | `dga-card-body` | Optional |
+| Footer | `dga-card-footer` | Optional |
+
+Footer inner classes: `.footer-text`, `.footer-actions`
+
+---
+
+## Variants
+
+Set `data-variant` on the root:
+
+| Value | Style |
+|-------|-------|
+| `default` | Shadow (`dga-shadow-md`) — default when omitted |
+| `stroke` | Border, no shadow |
+| `noshadow` | No shadow, no border |
+
+```html
+<div class="dga-card" data-variant="stroke">
+  <div class="dga-card-content">
+    <div class="dga-card-title">عنوان</div>
+    <div class="dga-card-body">محتوى</div>
+  </div>
+</div>
+```
+
+---
+
+## With utility spacing
+
+```html
+<div class="dga-card dga-p-4" data-variant="stroke">
+  ...
+</div>
+```
+
+---
+
+## Related
+
+- [Spacing](../foundations/spacing.md)
+- [Border radius](../foundations/radius.md)

package/docs/components/chart.md

@@ -0,0 +1,97 @@
+# Pie Chart
+
+CSS conic-gradient pie / donut chart with labels.
+
+**Source:** `src/styles/components/chart--pie.scss`, `src/scripts/chart.js`, `src/scripts/dga-pie-chart.js`  
+**Demo:** `index.html`  
+**JavaScript:** Optional — web component or `DGAChart` class
+
+---
+
+## Option 1: Web component (recommended)
+
+```html
+<dga-pie-chart
+  data='[
+    {"label":"البند الأول","from":"0%","to":"40%","color":"var(--dga-primary-100)"},
+    {"label":"البند الثاني","from":"40%","to":"70%","color":"var(--dga-gray-200)"},
+    {"label":"البند الثالث","from":"70%","to":"90%","color":"var(--dga-primary-700)"},
+    {"label":"البند الرابع","from":"90%","to":"100%","color":"var(--dga-primary-700)"}
+  ]'>
+</dga-pie-chart>
+```
+
+### Donut
+
+```html
+<dga-pie-chart hole data='[...]'></dga-pie-chart>
+```
+
+### Attributes
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `data` | `[]` | JSON array of segments (see data shape) |
+| `hole` | `false` | Present = donut (white center) |
+
+No `new DGAChart()` required. Update the `data` attribute to re-render.
+
+---
+
+## Option 2: Legacy markup + DGAChart
+
+```html
+<!-- Full pie -->
+<div id="chart1" class="dga-pie-chart" data-hole="false"></div>
+
+<!-- Donut -->
+<div id="chart2" class="dga-pie-chart" data-hole="true"></div>
+```
+
+```js
+import { DGAChart } from '@waaelg/dga-design-on-sass'
+
+const data = [
+  { label: 'البند الأول', from: '0%', to: '40%', color: 'var(--dga-primary-100)' },
+  { label: 'البند الثاني', from: '40%', to: '70%', color: 'var(--dga-gray-200)' },
+  { label: 'البند الثالث', from: '70%', to: '90%', color: 'var(--dga-primary-700)' },
+  { label: 'البند الرابع', from: '90%', to: '100%', color: 'var(--dga-primary-700)' },
+]
+
+new DGAChart(document.getElementById('chart1'), data)
+```
+
+| Attribute | Effect |
+|-----------|--------|
+| `data-hole="false"` | Solid pie |
+| `data-hole="true"` | Donut (white center) |
+
+Default size: 150×150px, centered with `margin: 0 auto`.
+
+---
+
+## Data shape
+
+| Field | Description |
+|-------|-------------|
+| `label` | Legend text |
+| `from` | Segment start (e.g. `0%`) |
+| `to` | Segment end (e.g. `40%`) |
+| `color` | Hex (`#2d7a5a`), CSS var (`var(--dga-primary-100)`), or token name (`primary-100`) |
+
+---
+
+## Generated markup
+
+JS adds:
+
+- `background: conic-gradient(...)` on the chart element
+- `.dga-pie-chart__labels` with `.dga-pie-chart__label` and `.dga-pie-chart__circle` swatches
+
+---
+
+## Related
+
+- [Web Components](../getting-started/web-components.md)
+- [JavaScript API](../getting-started/javascript-api.md)
+- [Colors](../foundations/colors.md)