@a.nemreen/dga-ui 0.2.0

package/README.md

@@ -0,0 +1,400 @@
+# `@a.nemreen/dga-ui`
+
+[![npm version](https://img.shields.io/npm/v/@a.nemreen/dga-ui.svg)](https://www.npmjs.com/package/@a.nemreen/dga-ui)
+[![license](https://img.shields.io/npm/l/@a.nemreen/dga-ui.svg)](https://github.com/nemreen/dga-angular/blob/main/LICENSE)
+[![Angular](https://img.shields.io/badge/Angular-19-DD0031?logo=angular&logoColor=white)](https://angular.dev)
+[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-v4-38B2AC?logo=tailwindcss&logoColor=white)](https://tailwindcss.com)
+
+Standalone Angular UI components for the DGA design system — forms, overlays, navigation, portal shell, and layout. Styled with Tailwind utilities mapped to [`@a.nemreen/dga-tokens`](https://www.npmjs.com/package/@a.nemreen/dga-tokens).
+
+> Version **0.1.x** until public API freeze.
+
+## Features
+
+- Standalone Angular 19 components (no NgModules)
+- RTL-first / Arabic-ready (logical CSS + locale-aware chrome)
+- Forms: input, select, checkbox, radio, switch, OTP, upload, date picker, …
+- Overlays: dialog, modal, drawer, toast, menu, tooltip
+- Shell: header, top bar, hero, footer, preloader
+- Feedback & a11y: alert, cookies, accessibility panel, skip link
+- Layout: card, section, grid, clamp, expandable
+
+## Install
+
+```bash
+npm install @a.nemreen/dga-ui @a.nemreen/dga-tokens @platformscode/icons
+```
+
+**Peers:** `@angular/core` / `@angular/common` / `@angular/platform-browser` ^19, `@a.nemreen/dga-tokens` ^0.1, `@platformscode/icons` ^0.0.11.
+
+## Library layout
+
+Sources live under `src/lib/<domain>/<component>/`. Place new work in the matching domain — do not add new top-level peers under `lib/`.
+
+| Domain | Use for |
+|--------|---------|
+| `primitives/` | Visual atoms (button, icon, badge, …) |
+| `forms/` | Inputs, selects, field chrome |
+| `overlays/` | Floating UI (dialog, toast, menu, …) |
+| `feedback/` | Status and user-response UI (alert, cookies, a11y, …) |
+| `navigation/` | Wayfinding (tabs, breadcrumb, side-nav, …) |
+| `layout/` | Structure wrappers (card, section, grid, …) |
+| `shell/` | Page chrome (header, footer, hero, …) |
+| `content/` | Content presentation (list, quote, metric, …) |
+| `data/` | Tables, charts, export |
+| `domain/` | Locale/region data helpers (not UI) |
+| `utils/` | Internal helpers only (not exported) |
+
+Consumers always import from `@a.nemreen/dga-ui` — do not deep-import library paths.
+
+## Setup
+
+```css
+@import 'tailwindcss';
+@import '@a.nemreen/dga-tokens/styles.css';
+```
+
+Load Arabic Google Fonts (IBM Plex default; see `@a.nemreen/dga-tokens` README / `DgaFontService`).
+
+Scan library sources so Tailwind keeps component utilities (path may vary):
+
+```css
+@source "../node_modules/@a.nemreen/dga-ui/**/*.{mjs,js}";
+```
+
+```ts
+import {
+  DgaButton,
+  DgaInput,
+  DgaLabel,
+  DgaBadge,
+  DgaAlert,
+  DgaCheckbox,
+  DgaRadio,
+  DgaSelect,
+  DgaNativeSelect,
+  DgaField,
+  DgaSpinner,
+  DgaDialog,
+  DgaToast,
+  DgaCard,
+  DgaDivider,
+  DgaIcon,
+} from '@a.nemreen/dga-ui';
+```
+
+## Components
+
+### Icon
+
+Two layers:
+
+1. **Chrome** — curated inline SVG via `name` (paints with the first frame; use in buttons, fields, menus).
+2. **Content** — HugeIcons Stroke Rounded font via `glyph` (opt into `@a.nemreen/dga-tokens/styles/icon-font.css`).
+
+```html
+<!-- Chrome (always available) -->
+<dga-icon name="search" size="sm" />
+<dga-icon name="arrowNext" size="sm" label="التالي" />
+
+<!-- Content (requires icon-font.css) -->
+<dga-icon glyph="search-01" size="xl" />
+<dga-icon glyph="notification-02" size="xl" tone="primary" />
+```
+
+Use `arrowNext` / `arrowPrev` for forward/back — they mirror under `dir="rtl"`. Prefer literal `arrowLeft` / `arrowRight` only when you mean that physical direction.
+
+Sizes (px): `2xs` 10 · `xs` 14 · `sm` 16 · `md` 18 · `lg` 20 · `xl` 24 · `2xl` 28 · `3xl` 32.
+
+Full SVG catalog remains available from [@platformscode/icons](https://www.npmjs.com/package/@platformscode/icons) when you need a glyph outside the curated `name` list.
+
+### Scroll to top
+
+Floating control that appears after the page scrolls past a threshold. Mount once at the app root; it stacks above `dga-accessibility` by default.
+
+```html
+<dga-scroll-top position="end" [threshold]="320" />
+```
+
+### Button
+
+```html
+<button dgaButton type="button">حفظ</button>
+<button dgaButton variant="outline" size="sm">إلغاء</button>
+<button dgaButton variant="danger" disabled>حذف</button>
+```
+
+### Input + Label + Field
+
+```html
+<label dgaLabel dgaRequired for="email">البريد</label>
+<input dgaInput id="email" type="email" />
+<textarea dgaInput rows="3"></textarea>
+
+<dga-field label="البريد" controlId="email" required hint="لن نشارك بريدك.">
+  <input dgaInput id="email" type="email" />
+</dga-field>
+```
+
+### Select
+
+Configurable select (search, multi, always-open):
+
+```html
+<dga-select [options]="cities" [(value)]="city" />
+<dga-select searchable [options]="cities" [(value)]="city" />
+<dga-select multiple [options]="cities" [(value)]="cities" />
+<dga-select multiple searchable [options]="cities" [(value)]="cities" />
+<dga-select openMode="always" [options]="cities" [(value)]="city" />
+```
+
+Native `<select>` styling for simple forms:
+
+```html
+<select dgaSelect>
+  <option value="riyadh">الرياض</option>
+</select>
+```
+
+### Checkbox + Radio
+
+```html
+<label>
+  <input dgaCheckbox type="checkbox" />
+  أوافق
+</label>
+
+<label>
+  <input dgaRadio type="radio" name="plan" value="basic" />
+  أساسية
+</label>
+```
+
+### Badge
+
+```html
+<dga-badge variant="success">مكتمل</dga-badge>
+```
+
+### Alert
+
+```html
+<dga-alert variant="warning" title="تنبيه">تحقق من البيانات.</dga-alert>
+<dga-alert dismissible (dismissed)="onDismiss()">يمكن إغلاقه</dga-alert>
+```
+
+### Spinner
+
+```html
+<dga-spinner />
+<dga-spinner size="lg" tone="neutral" />
+```
+
+### Preloader (optional first-load)
+
+Full-screen brand overlay; auto-hides when the document is ready and `minDuration` elapses. Omit the tag if you do not want it.
+
+```html
+<dga-preloader
+  brand="بوابة الخدمات"
+  label="جاري التحميل"
+  [minDuration]="1000"
+  [once]="true"
+  persist="local"
+/>
+```
+
+- `once` + `persist="local"` - show only on the visitor’s first visit  
+- `persist="session"` - once per tab session  
+- `persist="none"` or `[once]="false"` - every load  
+- Optional `logoSrc` replaces the default geometric mark  
+- `(closed)` fires after the exit animation  
+
+```ts
+import { DgaPreloader } from '@a.nemreen/dga-ui';
+```
+
+### Dialog
+
+```html
+<dga-dialog [(open)]="open" title="تأكيد">
+  <p>هل أنت متأكد؟</p>
+  <div dgaDialogActions>
+    <button dgaButton variant="ghost" (click)="open = false">إلغاء</button>
+    <button dgaButton (click)="confirm()">تأكيد</button>
+  </div>
+</dga-dialog>
+```
+
+### Modal
+
+```html
+<dga-modal
+  [(open)]="open"
+  title="تفاصيل الطلب"
+  description="راجع البيانات قبل المتابعة"
+  size="lg"
+  animation="scale"
+>
+  <p>محتوى النافذة المنبثقة.</p>
+  <div dgaModalActions>
+    <button dgaButton variant="ghost" (click)="open = false">إلغاء</button>
+    <button dgaButton (click)="confirm()">تأكيد</button>
+  </div>
+</dga-modal>
+```
+
+### Toast
+
+```html
+<dga-toast [(open)]="show" variant="success" title="تم">حُفظ السجل.</dga-toast>
+```
+
+### Tooltip / Switch / Progress / Nav (Wave I)
+
+```html
+<dga-switch [(checked)]="on" label="الإشعارات" />
+<a dgaLink href="#">رابط</a>
+<dga-progress [value]="60" />
+<dga-skeleton />
+<dga-skeleton [lines]="3" animation="shimmer" />
+<dga-skeleton shape="circle" size="lg" />
+<dga-tooltip title="مساعدة" text="وصف مختصر">
+  <button dgaButton size="sm">؟</button>
+</dga-tooltip>
+
+<dga-breadcrumb [items]="[{ label: 'الرئيسية', href: '#' }, { label: 'الحالي' }]" />
+<dga-tabs [(selected)]="tab">
+  <dga-tab value="a" label="أ">...</dga-tab>
+</dga-tabs>
+<dga-accordion>
+  <dga-accordion-item title="سؤال">جواب</dga-accordion-item>
+</dga-accordion>
+<dga-pagination [(page)]="page" [totalPages]="10" />
+```
+
+## Layout recipes
+
+Prefer DGA spacing tokens (`gap-md`, `p-xl`, `py-3xl`) over raw pixel values. For page width, use `max-w-(--container-*)` - plain `max-w-5xl` binds to the spacing scale in Tailwind v4.
+
+### Stack (column)
+
+```html
+<div class="flex flex-col gap-md">
+  <p>صف واحد</p>
+  <p>صف آخر</p>
+</div>
+```
+
+### Inline row
+
+```html
+<div class="flex flex-wrap items-center gap-md">
+  <button dgaButton>حفظ</button>
+  <button dgaButton variant="ghost">إلغاء</button>
+</div>
+```
+
+### Split (space between)
+
+```html
+<div class="flex items-center justify-between gap-xl">
+  <h2 class="text-display-sm">العنوان</h2>
+  <div class="flex gap-sm">…</div>
+</div>
+```
+
+### Responsive grid
+
+```html
+<div class="grid grid-cols-1 gap-lg md:grid-cols-2 lg:grid-cols-3">
+  <dga-card title="أ">…</dga-card>
+  <dga-card title="ب">…</dga-card>
+  <dga-card title="ج">…</dga-card>
+</div>
+```
+
+Or use the thin wrapper:
+
+```html
+<dga-grid [cols]="3" gap="lg">
+  <dga-card title="أ">…</dga-card>
+  <dga-card title="ب">…</dga-card>
+  <dga-card title="ج">…</dga-card>
+</dga-grid>
+```
+
+### Contained section
+
+```html
+<dga-section title="القسم" subtitle="وصف قصير" contained>
+  محتوى القسم
+</dga-section>
+```
+
+### Portal home shell (consumable across apps)
+
+Compose the official home template with library primitives only - no page-local CSS required:
+
+```html
+<dga-top-bar registrationId="00000000000" />
+
+<dga-header
+  appearance="portal"
+  mobileNav="sheet"
+  brand="شعار المنصة"
+  brandSlogan="بوابة الجهة"
+  brandHref="/"
+  [items]="navItems"
+  [actions]="headerActions"
+  (actionClick)="onAction($event)"
+/>
+<!-- mobileNav: sheet | fullscreen | push -->
+
+<dga-hero appearance="portal" [slides]="heroSlides" [(activeIndex)]="i" />
+
+<dga-section
+  width="wide"
+  tone="surface"
+  title="قسم من نحن"
+  subtitle="…"
+>
+  <button dgaSectionActions dgaButton variant="outline">إجراء ثانوي</button>
+  <dga-grid [cols]="4" gap="xl">
+    <dga-metric appearance="stat" value="1.5M" label="شخص">
+      <dga-icon-badge dgaMetricIcon>
+        <dga-icon name="user" tone="primary" />
+      </dga-icon-badge>
+    </dga-metric>
+  </dga-grid>
+</dga-section>
+
+<dga-card title="عنوان البطاقة" description="نص إضافي">
+  <dga-icon-badge dgaCardLead>
+    <dga-icon name="home" tone="primary" />
+  </dga-icon-badge>
+  <div dgaCardActions>
+    <button dgaButton variant="outline" size="sm">اجراء ثانوي</button>
+    <button dgaButton size="sm">اجراء</button>
+  </div>
+</dga-card>
+
+<dga-card>
+  <dga-card-media dgaCardMedia alt="خبر" />
+  …
+</dga-card>
+
+<dga-logo-tile label="شريك" />
+<dga-footer [columns]="footerColumns" copyright="…" />
+```
+
+Portal tokens (layout sizes): `--size-hero-portal` (491px), `--size-header-portal` (72px), `--size-icon-badge` (40px), `--size-dot` (16px).
+
+### Content + sticky aside
+
+```html
+<div class="mx-auto grid max-w-(--container-7xl) gap-3xl px-xl md:grid-cols-[1fr_auto]">
+  <main class="min-w-0">…</main>
+  <dga-side-info title="في هذه الصفحة" [items]="tocItems" />
+</div>
+```