@waaelg/dga-design-system 0.4.2

package/docs/getting-started/javascript-api.md

@@ -0,0 +1,204 @@
+# JavaScript API
+
+The package exports **plain JavaScript classes**, not Vue/React components.
+
+```js
+import {
+  DGAAccordion,
+  DGAAlert,
+  DGAChart,
+  DGACodeSnippet,
+  DGAMenuDropDown,
+  DGAVerifyBar,
+} from '@waaelg/dga-design-on-sass'
+```
+
+Importing the main entry also registers these custom elements:
+
+| Element | Legacy class |
+|---------|--------------|
+| `<dga-alert>` | `DGAAlert` |
+| `<dga-accordion>` | `DGAAccordion` |
+| `<dga-code-snippet>` | `DGACodeSnippet` |
+| `<dga-pie-chart>` | `DGAChart` |
+| `<dga-verify-bar>` | `DGAVerifyBar` |
+
+See [Web Components](./web-components.md) for plain HTML, ASP.NET, and framework usage.
+
+---
+
+## Important rules
+
+1. **Use HTML + `dga-*` classes** or **`<dga-*>` web components** — do not use `<DGAAlert />` in Vue/React.
+2. **Call `new ClassName()`** after the DOM is ready (legacy markup only).
+3. **CSS-only components** (button, card, forms) need no JavaScript.
+
+---
+
+## DGAAccordion
+
+**Web component:** `<dga-accordion>` with `<dga-accordion-item>` — no init required.
+
+**Legacy:** root element with class `dga-acc`
+
+```html
+<div class="dga-acc" id="faq">
+  <div class="dga-acc-item">
+    <button class="dga-acc-header" aria-expanded="false">
+      <span>Question</span>
+    </button>
+    <div class="dga-acc-content">
+      <div class="dga-acc-body">Answer</div>
+    </div>
+  </div>
+</div>
+```
+
+```js
+new DGAAccordion(document.getElementById('faq'))
+```
+
+Supports click and keyboard (Enter / Space).
+
+---
+
+## DGAAlert
+
+**Web component:** `<dga-alert variant="info-color" dismissible>` — no init required.
+
+**Legacy:** `.dga-alert` and close button with `[data-alert-close]`
+
+```js
+new DGAAlert() // listens on document
+```
+
+See [Alert component](../components/alert.md).
+
+---
+
+## DGAChart
+
+**Web component:** `<dga-pie-chart data='[...]'>` — no init required.
+
+**Legacy:** element with class `dga-pie-chart`
+
+```html
+<div id="chart" class="dga-pie-chart" data-hole="false"></div>
+```
+
+```js
+new DGAChart(document.getElementById('chart'), [
+  { label: 'Item 1', from: '0%', to: '40%', color: 'var(--dga-primary-100)' },
+  { label: 'Item 2', from: '40%', to: '100%', color: 'var(--dga-gray-200)' },
+])
+```
+
+Set `data-hole="true"` for donut style.
+
+---
+
+## DGACodeSnippet
+
+**Web component:** `<dga-code-snippet code="...">` — no init required.
+
+**Legacy:** initialize once for copy on manual markup:
+
+```js
+new DGACodeSnippet()
+```
+
+Copy buttons: `.dga-code-snippet-inline__copy` or `.dga-code-snippet-multiline__copy`
+
+---
+
+## DGAMenuDropDown
+
+**Requires:** `.dga-navbar` with `.dga-menu` and `.dga-navbar-toggler`
+
+```js
+new DGAMenuDropDown({ navbar: document.querySelector('.dga-navbar') })
+```
+
+---
+
+## DGAVerifyBar
+
+**Requires:** legacy IDs: `#dga-verify-bar`, `#dga-verifyBtn`, `#dga-verify-bar_content`
+
+```js
+const verifyBar = new DGAVerifyBar()
+const menu = new DGAMenuDropDown()
+verifyBar.menu = menu
+menu.verifyBar = verifyBar
+```
+
+**Alternative:** use `<dga-verify-bar>` web component (no manual init).
+
+---
+
+## Web components summary
+
+```html
+<dga-alert variant="success-color" title="Done" dismissible>Message</dga-alert>
+
+<dga-accordion>
+  <dga-accordion-item title="Question">Answer</dga-accordion-item>
+</dga-accordion>
+
+<dga-code-snippet code="npm install @waaelg/dga-design-on-sass"></dga-code-snippet>
+
+<dga-pie-chart data='[{"label":"A","from":"0%","to":"50%","color":"primary-100"}]'></dga-pie-chart>
+
+<dga-verify-bar></dga-verify-bar>
+```
+
+Full guide: [Web Components](./web-components.md).
+
+---
+
+## Vue example (legacy)
+
+```vue
+<script setup>
+import { onMounted, onUnmounted } from 'vue'
+import { DGAAlert } from '@waaelg/dga-design-on-sass'
+
+let alertInstance
+
+onMounted(() => {
+  alertInstance = new DGAAlert()
+})
+
+onUnmounted(() => {
+  alertInstance?.destroy()
+})
+</script>
+
+<template>
+  <div class="dga-alert" data-variant="success-color">
+    <!-- ... -->
+    <button class="dga-alert-close" data-alert-close aria-label="Close">×</button>
+  </div>
+</template>
+```
+
+---
+
+## Vite troubleshooting
+
+If you see `does not provide an export named 'DGAAlert'`:
+
+```bash
+rm -rf node_modules/.vite
+npm run dev
+```
+
+See [Installation](./installation.md#vite--vue).
+
+---
+
+## Related
+
+- [Web Components](./web-components.md)
+- [Installation](./installation.md)
+- [Components index](../README.md#components)

package/docs/getting-started/rtl-arabic.md

@@ -0,0 +1,89 @@
+# RTL & Arabic
+
+The DGA design system targets Saudi government websites. Arabic and RTL are first-class.
+
+---
+
+## HTML setup
+
+```html
+<html lang="ar" dir="rtl">
+```
+
+| Attribute | Value | Purpose |
+|-----------|-------|---------|
+| `lang` | `ar` | Arabic language |
+| `dir` | `rtl` | Right-to-left layout |
+
+For bilingual pages, set `dir` on a wrapper instead of `<html>`:
+
+```html
+<div dir="rtl" lang="ar">
+  <!-- Arabic content -->
+</div>
+```
+
+---
+
+## Font
+
+**IBM Plex Sans Arabic** loads automatically with the stylesheet:
+
+```scss
+body {
+  font-family: "IBM Plex Sans Arabic", sans-serif;
+}
+```
+
+No extra font import is required when using `@waaelg/dga-design-on-sass/style.css`.
+
+---
+
+## Logical properties
+
+Components use logical CSS where possible (`border-inline-start`, `text-align: start`) so they work in both RTL and LTR.
+
+| Physical | Logical (preferred) |
+|----------|---------------------|
+| `dga-text-left` | `dga-text-start` |
+| `dga-text-right` | `dga-text-end` |
+| `dga-pl-*` | works; axis follows direction |
+
+---
+
+## Button icons
+
+Use `dga-btn__icon` for icons inside buttons. In RTL, icon placement follows flex direction.
+
+```html
+<button class="dga-btn dga-btn-primary dga-btn-md">
+  الاجراء الرئيسي
+  <img class="dga-btn__icon" src="arrow.svg" alt="" />
+</button>
+```
+
+---
+
+## Grid and flex
+
+Grid and flex utilities are direction-aware when using `start` / `end`:
+
+```html
+<div class="dga-d-flex dga-justify-content-start dga-gap-4">
+  <button class="dga-btn dga-btn-primary">زر</button>
+</div>
+```
+
+---
+
+## Verify bar
+
+The Saudi government verification bar is Arabic by default. Use `<dga-verify-bar>` or the verify bar markup from `verify-bar.html`.
+
+---
+
+## Related
+
+- [Installation](./installation.md)
+- [Typography](../foundations/typography.md)
+- [Grid](../foundations/grid.md)

package/docs/getting-started/web-components.md

@@ -0,0 +1,134 @@
+# Web Components
+
+Web components are **standard HTML** — they work anywhere you can write markup and load a script: static HTML, **ASP.NET Core (`.cshtml`)**, PHP, Blazor (with script import), Vue, React, etc.
+
+Importing `@waaelg/dga-design-on-sass` registers these custom elements:
+
+| Element | Legacy alternative |
+|---------|-------------------|
+| `<dga-alert>` | `DGAAlert` + HTML markup |
+| `<dga-accordion>` + `<dga-accordion-item>` | `DGAAccordion` + HTML markup |
+| `<dga-code-snippet>` | `DGACodeSnippet` + HTML markup |
+| `<dga-pie-chart>` | `DGAChart` + HTML markup |
+| `<dga-verify-bar>` | `DGAVerifyBar` + fixed IDs |
+
+No manual `customElements.define` or `new ClassName()` is required.
+
+---
+
+## Plain HTML
+
+```html
+<!DOCTYPE html>
+<html lang="ar" dir="rtl">
+<head>
+  <link rel="stylesheet" href="./node_modules/@waaelg/dga-design-on-sass/dist/style.css" />
+</head>
+<body>
+  <dga-alert variant="success-color" title="نجاح" dismissible>
+    تمت العملية بنجاح
+  </dga-alert>
+
+  <script type="module">
+    import './node_modules/@waaelg/dga-design-on-sass/dist/index.js'
+  </script>
+</body>
+</html>
+```
+
+---
+
+## ASP.NET Core (Razor / `.cshtml`)
+
+Copy `dist/style.css` and `dist/index.js` into `wwwroot/lib/dga/` (or reference them from `node_modules` via LibMan / build step).
+
+**`_Layout.cshtml`**
+
+```html
+<link rel="stylesheet" href="~/lib/dga/style.css" asp-append-version="true" />
+<script type="module" src="~/lib/dga/index.js" asp-append-version="true"></script>
+```
+
+**View (e.g. `Index.cshtml`)**
+
+```html
+<dga-alert variant="success-color" title="@Model.Title" dismissible>
+  @Model.Message
+</dga-alert>
+
+<dga-accordion>
+  <dga-accordion-item title="السؤال الأول">
+  @Html.Raw(Model.FaqAnswer)
+  </dga-accordion-item>
+</dga-accordion>
+```
+
+Custom element tag names are lowercase in HTML — Razor outputs them like any other markup. No Vue/React setup needed.
+
+For `dga-pie-chart`, pass JSON in the `data` attribute (escape quotes in Razor or build the attribute server-side).
+
+---
+
+## Bundlers (Vite, webpack, etc.)
+
+```js
+import '@waaelg/dga-design-on-sass/style.css'
+import '@waaelg/dga-design-on-sass'
+```
+
+Then use `<dga-alert>`, `<dga-accordion>`, etc. in your templates.
+
+---
+
+## Framework notes (Vue / React)
+
+These are **not** Vue or React components — do not import them as `<DGAAlert />`. Use the HTML tags directly after importing the package.
+
+**Vue 3** — if the compiler warns about unknown tags:
+
+```js
+// vite.config.js
+export default defineConfig({
+  vue: {
+    compilerOptions: {
+      isCustomElement: (tag) => tag.startsWith('dga-'),
+    },
+  },
+})
+```
+
+**React** — use lowercase tag names in JSX. TypeScript may need `declare global` for `dga-*` intrinsic elements.
+
+Framework-specific examples: [Installation](./installation.md).
+
+---
+
+## Events
+
+| Element | Event | When |
+|---------|-------|------|
+| `<dga-alert>` | `dga-alert-dismiss` | User clicks dismiss |
+| `<dga-code-snippet>` | `dga-code-copy` | Copy succeeds |
+
+```js
+document.querySelector('dga-alert')?.addEventListener('dga-alert-dismiss', () => {
+  console.log('Alert dismissed')
+})
+```
+
+---
+
+## When to use legacy classes
+
+- Existing HTML with `dga-*` classes already in place
+- Multi-tab code snippets with custom tab logic
+- Verify bar integrated with legacy navbar IDs
+
+Component docs describe both options: [Alert](../components/alert.md), [Accordion](../components/accordion.md), [Code snippet](../components/code-snippet.md), [Pie chart](../components/chart.md), [Verify bar](../components/verify-bar.md).
+
+---
+
+## Related
+
+- [Installation](./installation.md)
+- [JavaScript API](./javascript-api.md)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@waaelg/dga-design-system",
+  "version": "0.4.2",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./style.css": "./dist/style.css"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/waaelg/dga-design-system.git"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "sass": "^1.93.2",
+    "vite": "^7.1.7"
+  },
+  "dependencies": {
+    "@popperjs/core": "^2.11.8",
+    "@tailwindcss/vite": "^4.1.16",
+    "tailwindcss": "^4.1.16"
+  },
+  "keywords": [
+    "dga",
+    "saudi",
+    "design-system",
+    "sass"
+  ],
+  "author": "Wael Alghamdi",
+  "license": "MIT"
+}