@waaelg/dga-design-system 0.4.2

package/docs/components/code-snippet.md

@@ -0,0 +1,110 @@
+# Code Snippet
+
+Inline and multi-line code blocks with copy button.
+
+**Source:** `src/styles/components/code-snippet.scss`, `src/scripts/codeSnippet.js`, `src/scripts/dga-code-snippet.js`  
+**Demo:** `index.html`  
+**JavaScript:** Optional — web component or `DGACodeSnippet` class
+
+---
+
+## Option 1: Web component (recommended)
+
+### Inline
+
+```html
+<dga-code-snippet code="npm install @waaelg/dga-design-on-sass"></dga-code-snippet>
+```
+
+Or with text content:
+
+```html
+<dga-code-snippet>npm install @waaelg/dga-design-on-sass</dga-code-snippet>
+```
+
+### Multiline
+
+```html
+<dga-code-snippet multiline code="const app = createApp(App)
+app.mount('#app')"></dga-code-snippet>
+```
+
+### Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `code` | Code text to display and copy |
+| `multiline` | Present = multi-line block layout |
+
+Copy fires `dga-code-copy` on success. No `new DGACodeSnippet()` required.
+
+> Tabbed multi-line snippets (Java / Python tabs) are **legacy markup only** — implement tab switching in your app.
+
+---
+
+## Option 2: Legacy markup + DGACodeSnippet
+
+### Inline snippet
+
+```html
+<div class="dga-code-snippet-inline">
+  <div class="dga-code-snippet-inline__content">npm install @waaelg/dga-design-on-sass</div>
+  <button type="button" class="dga-code-snippet-inline__copy"
+          aria-label="Copy code" data-copied="false">
+    <!-- copy icon SVG -->
+  </button>
+</div>
+```
+
+```js
+import { DGACodeSnippet } from '@waaelg/dga-design-on-sass'
+new DGACodeSnippet()
+```
+
+### Multi-line snippet (with tabs)
+
+```html
+<div class="dga-code-snippet-multiline">
+  <div class="dga-code-snippet-multiline__tabs" dir="ltr">
+    <button type="button" class="dga-code-snippet-multiline__tab" data-active="true">Java</button>
+    <button type="button" class="dga-code-snippet-multiline__tab">Python</button>
+  </div>
+
+  <div class="dga-code-snippet-multiline__body">
+    <ol class="dga-code-snippet-multiline__lines">
+      <li></li><li></li><li></li>
+    </ol>
+    <pre class="dga-code-snippet-multiline__code"><code>// Your code here</code></pre>
+    <button type="button" class="dga-code-snippet-multiline__copy"
+            aria-label="Copy code" data-copied="false"></button>
+  </div>
+
+  <div class="dga-code-snippet-multiline__footer" dir="ltr">Show More</div>
+</div>
+```
+
+Tab switching is not wired in JS by default — implement in your app or extend `DGACodeSnippet`.
+
+---
+
+## Copy behavior
+
+- Web component: built-in copy on button click
+- Legacy: `DGACodeSnippet` listens for clicks on `.dga-code-snippet-inline__copy` and `.dga-code-snippet-multiline__copy`
+- Sets `data-copied="true"` briefly after successful copy
+
+---
+
+## Styling notes
+
+- Inline content uses `direction: ltr` for code
+- Monospace font stack built in
+- Copy button shows success state (green) when `data-copied="true"`
+
+---
+
+## Related
+
+- [Web Components](../getting-started/web-components.md)
+- [JavaScript API](../getting-started/javascript-api.md)
+- [Installation](../getting-started/installation.md)

package/docs/components/divider.md

@@ -0,0 +1,54 @@
+# Divider
+
+Horizontal or vertical separator lines.
+
+**Source:** `src/styles/components/divider.scss`  
+**Demo:** `index.html`  
+**JavaScript required:** No
+
+---
+
+## Horizontal divider
+
+```html
+<div class="dga-divider" data-variant="primary" data-direction="h"></div>
+```
+
+Default is horizontal if `data-direction` is omitted (height 1px, width 192px max 90%).
+
+---
+
+## Vertical divider
+
+```html
+<div class="dga-divider" data-variant="primary" data-direction="v"></div>
+```
+
+Width 1px, height 192px max 90%. Use between inline items (e.g. tags).
+
+---
+
+## Variants
+
+| `data-variant` | Color |
+|----------------|-------|
+| `secondary` | Gray (`$dga-gray-300`) |
+| `primary` | Saudi green (`$dga-sa-600`) |
+
+---
+
+## Example with tags
+
+```html
+<div class="dga-d-flex dga-gap-2 dga-align-items-center">
+  <span class="dga-tag">Tag 1</span>
+  <div class="dga-divider" data-variant="primary" data-direction="v"></div>
+  <span class="dga-tag">Tag 2</span>
+</div>
+```
+
+---
+
+## Related
+
+- [Tag](./tag.md)

package/docs/components/forms.md

@@ -0,0 +1,123 @@
+# Forms
+
+Input, select, textarea, and label components.
+
+**Source:** `src/styles/components/input.scss`, `select.scss`, `textarea.scss`, `label.scss`  
+**Demo:** `index.html`  
+**JavaScript required:** No
+
+---
+
+## Label
+
+```html
+<label for="field-id" class="dga-label">حقل نص عادي</label>
+```
+
+Always pair `for` with the control `id`.
+
+---
+
+## Text input
+
+```html
+<label for="dga-input" class="dga-label">حقل نص عادي</label>
+<input type="text" id="dga-input" class="dga-input" />
+```
+
+### Error state
+
+```html
+<input type="text" class="dga-input dga-input-error" aria-invalid="true" />
+```
+
+| Class | Purpose |
+|-------|---------|
+| `dga-input` | Base input (40px height, full width) |
+| `dga-input-error` | Red border and error underline |
+
+---
+
+## Select
+
+```html
+<label for="dga-select" class="dga-label">قائمة منسدلة</label>
+<select id="dga-select" class="dga-select">
+  <option>خيار 1</option>
+  <option>خيار 2</option>
+</select>
+```
+
+### Error state
+
+```html
+<select class="dga-select error" aria-invalid="true">...</select>
+```
+
+> Note: select uses class `error`, not `dga-select-error`.
+
+---
+
+## Textarea
+
+```html
+<label for="dga-textarea" class="dga-label">رسالة</label>
+<textarea id="dga-textarea" class="dga-textarea"></textarea>
+```
+
+### Error state
+
+```html
+<textarea class="dga-textarea dga-textarea-error" aria-invalid="true"></textarea>
+```
+
+Min height: 96px. Resizable by default.
+
+---
+
+## Full form example
+
+```html
+<div class="dga-d-flex dga-flex-col dga-gap-3">
+  <div>
+    <label for="name" class="dga-label">الاسم</label>
+    <input type="text" id="name" class="dga-input" />
+  </div>
+  <div>
+    <label for="role" class="dga-label">الدور</label>
+    <select id="role" class="dga-select">
+      <option>مواطن</option>
+      <option>موظف</option>
+    </select>
+  </div>
+  <div>
+    <label for="message" class="dga-label">الرسالة</label>
+    <textarea id="message" class="dga-textarea"></textarea>
+  </div>
+</div>
+```
+
+---
+
+## States
+
+All form controls support:
+
+- **Hover** — darker border
+- **Focus** — bottom accent line + shadow
+- **Active** — partial underline + gray background
+- **Error** — red border (see classes above)
+
+---
+
+## Accessibility
+
+- Always use `<label class="dga-label">` with matching `for` / `id`
+- Set `aria-invalid="true"` on error fields
+- Add error message text linked with `aria-describedby`
+
+---
+
+## Related
+
+- [Label](./forms.md#label) · [Button](./button.md)

package/docs/components/link.md

@@ -0,0 +1,52 @@
+# Link
+
+Styled anchor links for inline navigation.
+
+**Source:** `src/styles/components/link.scss`  
+**Demo:** `index.html`  
+**JavaScript required:** No
+
+---
+
+## Basic link
+
+```html
+<a href="#" class="dga-link">Link</a>
+```
+
+Saudi green color (`$dga-sa-600`), underline on hover.
+
+---
+
+## Variants
+
+| Attribute | Effect |
+|-----------|--------|
+| (default) | No underline until hover |
+| `data-variant="inline"` | Always underlined |
+
+```html
+<a href="#" class="dga-link" data-variant="inline">Inline link</a>
+```
+
+---
+
+## States
+
+- **Hover** — lighter green + underline
+- **Active** — darker green + underline
+- **Focus** — bottom border accent
+
+---
+
+## Accessibility
+
+- Use descriptive link text (not "click here")
+- External links: add `rel="noopener"` and indicate opens in new tab if needed
+
+---
+
+## Related
+
+- [Breadcrumb](./breadcrumb.md)
+- [Button](./button.md) — for actions use `<button>`, not links

package/docs/components/navbar.md

@@ -0,0 +1,93 @@
+# Navbar
+
+Responsive navigation with dropdown menus and mobile toggle.
+
+**Source:** `src/styles/components/navbar.scss`  
+**Demo:** `index.html` (header)  
+**JavaScript required:** Yes — `DGAMenuDropDown`
+
+---
+
+## HTML structure
+
+```html
+<nav class="dga-navbar dga-px-3" role="navigation" aria-label="Main navigation">
+  <a class="dga-navbar-brand" href="#">
+    <img src="logo.svg" alt="Site name" />
+  </a>
+
+  <ul class="dga-menu">
+    <li>
+      <a class="dga-menu-item" href="#">Link</a>
+    </li>
+    <li>
+      <a class="dga-menu-item dga-has-dropdown" href="#" role="button"
+         aria-expanded="false" aria-haspopup="true">
+        الرئيسية
+      </a>
+      <div class="dga-dropdown">
+        <div class="dga-dropdown-content">
+          <ul>
+            <li><a href="#">Link</a></li>
+            <li><a href="#">Link</a></li>
+          </ul>
+        </div>
+      </div>
+    </li>
+  </ul>
+
+  <button class="dga-navbar-toggler" aria-label="Open menu" aria-expanded="false"></button>
+</nav>
+```
+
+---
+
+## Classes
+
+| Class | Purpose |
+|-------|---------|
+| `dga-navbar` | Root nav container (72px height) |
+| `dga-navbar-brand` | Logo / brand link |
+| `dga-menu` | Horizontal menu list |
+| `dga-menu-item` | Nav link |
+| `dga-has-dropdown` | Item with dropdown chevron |
+| `dga-menu-item-with-icon` | Item with trailing icon |
+| `dga-menu-icon` | Icon inside menu item |
+| `dga-dropdown` | Dropdown panel |
+| `dga-dropdown-content` | Dropdown inner content |
+| `dga-dropdwon-title` | Section title in dropdown (note spelling in source) |
+| `dga-navbar-toggler` | Mobile menu button |
+
+---
+
+## JavaScript
+
+```js
+import { DGAMenuDropDown, DGAVerifyBar } from '@waaelg/dga-design-on-sass'
+
+const menu = new DGAMenuDropDown({
+  navbar: document.querySelector('.dga-navbar'),
+})
+
+// Optional: coordinate with verify bar
+const verifyBar = new DGAVerifyBar()
+verifyBar.menu = menu
+menu.verifyBar = verifyBar
+```
+
+Handles desktop dropdowns, mobile slide-out menu, keyboard, and resize.
+
+---
+
+## Accessibility
+
+- `role="navigation"` and `aria-label` on `<nav>`
+- Dropdown triggers: `role="button"`, `aria-expanded`, `aria-haspopup`
+- Toggler: `aria-label`, update `aria-expanded` when open
+
+---
+
+## Related
+
+- [Verify bar](./verify-bar.md)
+- [JavaScript API](../getting-started/javascript-api.md)

package/docs/components/table.md

@@ -0,0 +1,69 @@
+# Table
+
+Data tables with optional contained and striped styles.
+
+**Source:** `src/styles/components/table.scss`  
+**Demo:** `index.html`  
+**JavaScript required:** No
+
+---
+
+## Basic table
+
+```html
+<table class="dga-table" data-contained="true" data-striped="true">
+  <thead>
+    <tr>
+      <th>الاسم</th>
+      <th>العمر</th>
+      <th>المدينة</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>أحمد</td>
+      <td>30</td>
+      <td>الرياض</td>
+    </tr>
+    <tr>
+      <td>سارة</td>
+      <td>25</td>
+      <td>جدة</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+---
+
+## Data attributes
+
+| Attribute | Effect |
+|-----------|--------|
+| `data-contained="true"` | Rounded border wrapper, internal dividers |
+| `data-striped="true"` | Alternating row background |
+
+Both can be combined.
+
+---
+
+## Styling details
+
+- Header: gray background, 48px height, 12px font
+- Body rows: 64px height, 14px font
+- Row hover: light gray highlight
+- Text alignment: `text-align: start` (RTL-aware)
+
+---
+
+## Accessibility
+
+- Use `<thead>`, `<tbody>`, `<th>`, `<td>` semantically
+- Add `<caption>` for table description when helpful
+- For sortable tables, add ARIA sort attributes in your app logic
+
+---
+
+## Related
+
+- [Grid](../foundations/grid.md)

package/docs/components/tag.md

@@ -0,0 +1,76 @@
+# Tag
+
+Compact labels for status, categories, and metadata.
+
+**Source:** `src/styles/components/tag.scss`  
+**Demo:** `index.html`  
+**JavaScript required:** No
+
+---
+
+## Basic tag
+
+```html
+<span class="dga-tag">تاق افتراضي</span>
+```
+
+Use `<span class="dga-tag">` — includes a default info icon on the left (LTR) or right (RTL).
+
+---
+
+## Variants
+
+| `data-variant` | Color |
+|----------------|-------|
+| (default) | Gray |
+| `success` | Green |
+| `info` | Blue |
+| `warning` | Orange |
+
+```html
+<span class="dga-tag" data-variant="success">تاق نجاح</span>
+<span class="dga-tag" data-variant="info">تاق معلومة</span>
+<span class="dga-tag" data-variant="warning">تاق تحذير</span>
+```
+
+---
+
+## Modifiers
+
+| Attribute | Effect |
+|-----------|--------|
+| `data-outline="true"` | Outlined border |
+| `data-rounded="true"` | Pill shape |
+| `data-icononly="true"` | Circle icon only (no text) |
+
+```html
+<span class="dga-tag" data-outline="true">تاق بحدود</span>
+<span class="dga-tag" data-outline="true" data-rounded="true">تاق مدور بحدود</span>
+<span class="dga-tag" data-variant="warning" data-rounded="true" data-icononly="true"></span>
+```
+
+---
+
+## Combined example
+
+```html
+<div class="dga-d-flex dga-flex-wrap dga-gap-2 dga-align-items-center">
+  <span class="dga-tag" data-outline="true">تاق بحدود</span>
+  <span class="dga-tag">تاق افتراضي</span>
+  <span class="dga-tag" data-variant="success">تاق نجاح</span>
+  <div class="dga-divider" data-variant="primary" data-direction="v"></div>
+  <span class="dga-tag" data-variant="info" data-rounded="true">تاق معلومة</span>
+</div>
+```
+
+---
+
+## RTL
+
+Icon position flips with `[dir="rtl"]` on parent or `dir="rtl"` on the tag.
+
+---
+
+## Related
+
+- [Divider](./divider.md)

package/docs/components/verify-bar.md

@@ -0,0 +1,79 @@
+# Verify Bar
+
+Saudi government official site verification banner.
+
+**Source:** `src/styles/components/verifyBar.scss`, `src/scripts/verifyBar.js`, `src/scripts/dga-verify-bar.js`  
+**Demo:** `verify-bar.html`, `index.html`  
+**JavaScript:** Optional — web component or `DGAVerifyBar` class
+
+---
+
+## Option 1: Web component (recommended)
+
+Import the package once — registers `<dga-verify-bar>` automatically:
+
+```html
+<dga-verify-bar></dga-verify-bar>
+```
+
+### Custom attributes
+
+```html
+<dga-verify-bar
+  domain=".edu.sa"
+  registration-number="20250105758"
+  registration-link="https://raqmi.dga.gov.sa/platforms/platforms/9ebc5e60-9081-4653-bfb9-08dd2a2f8633/platform-license">
+</dga-verify-bar>
+```
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `domain` | `.edu.sa` | Official domain suffix shown in copy |
+| `registration-number` | `20250105758` | DGA registration number |
+| `registration-link` | DGA Raqmi URL | Link to platform license |
+
+No manual JS init required when using the web component.
+
+---
+
+## Option 2: Legacy markup + DGAVerifyBar
+
+Requires fixed element IDs:
+
+- `#dga-verify-bar`
+- `#dga-verifyBtn`
+- `#dga-verify-bar_content`
+
+```js
+import { DGAVerifyBar, DGAMenuDropDown } from '@waaelg/dga-design-on-sass'
+
+const verifyBar = new DGAVerifyBar()
+const menu = new DGAMenuDropDown()
+verifyBar.menu = menu
+menu.verifyBar = verifyBar
+```
+
+Use this when integrating with the legacy HTML structure in `index.html`.
+
+---
+
+## Styling
+
+- Background: `dga-bg-gray-100`
+- Toggle button: `dga-btn dga-btn-subtle dga-text-primary-500`
+- Expandable panel with domain and HTTPS verification info
+- Arabic copy by default
+
+---
+
+## Assets
+
+The web component references SVG assets (`saudiFlag.svg`, `link-icon.svg`, etc.). Serve them from your app `public` folder or configure paths in your build.
+
+---
+
+## Related
+
+- [Navbar](./navbar.md) — coordinate open/close with mobile menu
+- [JavaScript API](../getting-started/javascript-api.md)
+- [RTL & Arabic](../getting-started/rtl-arabic.md)