ngx-kit 5.0.0 → 6.0.1

package/shared/README.md

@@ -0,0 +1,117 @@
+# ngx-kit/shared
+
+ابزارها و سرویس‌های مشترکی که بقیه‌ی بسته‌های `ngx-kit` روشون بنا شدن: مدیریت اورلی/دیالوگ، تشخیص جهت صفحه (RTL/LTR)، تشخیص تنظیمات مرورگر، و چند کامپوننت پایه‌ی قابل‌استفاده‌ی مجدد (اسلایدر، رنج‌اسلایدر، صفحه‌ی اشباع رنگ).
+
+معمولاً مستقیم به این پکیج نیازی ندارید — بقیه‌ی بسته‌ها به‌صورت خودکار بهش وابسته‌ان. ولی اگه دارید یه کامپوننت سفارشی می‌سازید که باید با بقیه‌ی کتابخونه هم‌خونی داشته باشه (دارک‌مود، RTL، درگ‌وپرفورمنس)، از همین ابزارها استفاده کنید.
+
+## نصب
+
+```bash
+npm install ngx-kit
+```
+
+سبک‌های پایه (شامل `color-scheme` که دارک‌مود رو فعال می‌کنه) رو یک‌بار در سراسر اپ ایمپورت کنید:
+
+```scss
+// styles.scss
+@import 'ngx-kit/styles/all.css';
+```
+
+## سرویس‌ها
+
+### `OverlayService`
+
+موتور اصلی پشتِ همه‌ی چیزهای شناور کتابخونه (منو، دیالوگ، پاپ‌آپ‌های رنگ/گرادیان/زاویه). یک المنت انگولاری رو داخل یک `<dialog>` بومیِ مرورگر (`showModal()`) نمایش می‌ده و نسبت به یک anchor موقعیت‌دهی می‌کنه.
+
+```ts
+import { OverlayService } from 'ngx-kit/shared';
+
+const overlay = inject(OverlayService);
+const viewContainerRef = inject(ViewContainerRef);
+
+const ref = overlay.open({
+  component: MyComponent,
+  viewContainerRef,
+  anchor: buttonElementRef.nativeElement,
+  placement: 'bottom', // 'top' | 'bottom' | 'auto'
+  alignment: 'start', // 'start' | 'center' | 'end'
+  margin: 8,
+});
+
+ref.close(); // OverlayRef.close() آرگومان یا afterClosed نداره؛ برای اون‌جور رفتار (نتیجه‌ی بازگشتی، افترکلوز) از ngx-kit/dialog استفاده کنید که روی همین سرویس بنا شده
+```
+
+چیزهایی که به‌صورت خودکار برات مدیریت می‌شه:
+
+- **موقعیت‌دهی هوشمند**: اگه فضای کافی پایین anchor نباشه، خودکار بالا می‌ره (`placement:'auto'`).
+- **بستن با کلیک بیرون**: با تشخیص کلیک روی backdrop، نه با listener سراسری روی document.
+- **پشته‌بندی درست**: چند اورلیِ هم‌زمان (مثلاً یه منوی زیرمنو‌دار) درست کار می‌کنن؛ Escape فقط آخرین (بالاترین) اورلی رو می‌بنده.
+- **بازگشتِ فوکوس**: بعد از بسته‌شدن، فوکوس به همون المنتی که قبلش فوکوس داشت برمی‌گرده (دسترس‌پذیری).
+- **RTL خودکار**: alignment و placement بر اساس جهت واقعیِ صفحه (نه فقط یه فرض ثابت) حساب می‌شن.
+
+### `DirectionService`
+
+یه سیگنال (`isRtl(): boolean`) که با `MutationObserver` روی attribute-ی `dir` عنصر `<html>` گوش می‌ده و به‌محض تغییرش، ری‌اکتیو آپدیت می‌شه — یعنی اگه اپ شما زبان رو runtime عوض کنه، همه‌چیز خودکار هماهنگ می‌مونه.
+
+```ts
+const direction = inject(DirectionService);
+direction.isRtl(); // signal<boolean>
+```
+
+### `BrowserService`
+
+```ts
+const browser = inject(BrowserService);
+browser.prefersDarkMode; // boolean — یه‌بار در لحظه‌ی ساخت سرویس خونده می‌شه
+```
+
+## ابزارهای Utility
+
+### `startDragSession(callbacks)`
+
+جایگزینِ الگوی مشکل‌دارِ `@HostListener('document:mousemove', ...)` که listener رو برای کل عمر کامپوننت روی `document` نگه می‌داره (حتی وقتی دراگی در جریان نیست — یه مشکل واقعیِ پرفورمنس روی صفحاتی با چند نمونه‌ی هم‌زمان). این تابع فقط در طول یک درگِ واقعی، listener اضافه می‌کنه و خودش پاک می‌کنه؛ `touchmove` هم با `{passive:false}` مدیریت می‌شه، پس درگ‌کردن روی موبایل صفحه رو اسکرول نمی‌کنه.
+
+```ts
+import { startDragSession } from 'ngx-kit/shared';
+
+let stop: (() => void) | undefined;
+
+function onPointerDown(ev: MouseEvent | TouchEvent) {
+  stop?.();
+  stop = startDragSession({
+    onMove: (ev) => {
+      /* آپدیت موقعیت */
+    },
+    onEnd: () => {
+      stop = undefined;
+    },
+  });
+}
+```
+
+> اگه کامپوننت‌تون `OnPush` هست و از `startDragSession` (به‌جای `@HostListener`) استفاده می‌کنید، حتماً داخل `onMove`/`onEnd` خودتون `ChangeDetectorRef.markForCheck()` رو صدا بزنید — برخلاف `@HostListener` که خودکار view رو dirty می‌کنه، `addEventListener` دستی این کار رو نمی‌کنه.
+
+### `getOffsetPosition(event, element)`
+
+موقعیت pointer/touch رو نسبت به گوشه‌ی بالا-چپِ یه المنت مشخص برمی‌گردونه؛ برای پیاده‌سازیِ کامپوننت‌های درگ‌محور (اسلایدر، انتخاب‌گر رنگ و ...) استفاده می‌شه.
+
+### `mergeConfig(base, override)`
+
+ادغام عمیقِ دو آبجکت کانفیگ (برای الگوی `provideXxx({...})` که همه‌ی کتابخونه ازش استفاده می‌کنه).
+
+## کامپوننت‌های پایه
+
+اینا رو مستقیم هم می‌شه استفاده کرد، ولی بیشتر به‌عنوان بلوک‌های سازنده‌ی کامپوننت‌های دیگه (مثل `color-picker`, `box-shadow`) طراحی شدن:
+
+| کامپوننت               | Selector             | توضیح                                                               |
+| ---------------------- | -------------------- | ------------------------------------------------------------------- |
+| `SliderComponent`      | `slider`             | اسلایدر تک‌مقداره، `ControlValueAccessor`، `[min]`/`[max]`/`[step]` |
+| `RangeSliderComponent` | `range-slider`       | اسلایدر بازه‌ای (دو thumb)                                          |
+| `SaturationComponent`  | داخلی (color-picker) | صفحه‌ی دوبعدیِ انتخاب اشباع/روشنایی رنگ                             |
+
+## دارک‌مود و RTL
+
+هر دو مستقیماً روی `ngx-kit/shared` تکیه دارن:
+
+- **دارک‌مود**: از تابع CSS بومیِ `light-dark()` استفاده می‌شه. برای این‌که کار کنه، باید `color-scheme: light dark` (یا `only light`/`only dark` برای force کردن دستی) روی `:root` ست بشه — این کار با ایمپورت‌کردن `ngx-kit/styles/all.css` خودکار انجام می‌شه. برای force کردن دستیِ تم (مستقل از `prefers-color-scheme` سیستم)، `data-ngx-theme="dark"` یا `"light"` رو روی `<html>`/`<body>` بذارید.
+- **RTL**: با `dir="rtl"` روی `<html>` فعال می‌شه؛ همه‌جای کتابخونه از CSS logical properties (`inset-inline-start` و ...) استفاده شده، پس نیازی به استایل جداگانه نیست.

package/styles/all.css

@@ -1,3 +1,17 @@
+:root {
+  color-scheme: light dark;
+}
+
+:root[data-ngx-theme=light],
+[data-ngx-theme=light] {
+  color-scheme: only light;
+}
+
+:root[data-ngx-theme=dark],
+[data-ngx-theme=dark] {
+  color-scheme: only dark;
+}
+
 dialog.ngx-ui-overlay::backdrop {
   background: transparent;
 }
@@ -20,6 +34,19 @@ dialog.ngx-ui-overlay::backdrop {
     opacity: 0;
   }
 }
+dialog.ngx-image-viewer-dialog {
+  border: none;
+  padding: 1rem;
+  max-inline-size: 96vw;
+  max-block-size: 96vh;
+  inline-size: min(900px, 96vw);
+  background: light-dark(#ffffff, #1c1c20);
+  border-radius: 12px;
+}
+dialog.ngx-image-viewer-dialog::backdrop {
+  background: rgba(0, 0, 0, 0.75);
+}
+
 /* ---------- confetti (success only) ---------- */
 .confetti {
   position: absolute;

package/styles/image-viewer.css

@@ -0,0 +1,12 @@
+dialog.ngx-image-viewer-dialog {
+  border: none;
+  padding: 1rem;
+  max-inline-size: 96vw;
+  max-block-size: 96vh;
+  inline-size: min(900px, 96vw);
+  background: light-dark(#ffffff, #1c1c20);
+  border-radius: 12px;
+}
+dialog.ngx-image-viewer-dialog::backdrop {
+  background: rgba(0, 0, 0, 0.75);
+}

package/types/ngx-kit-box-shadow.d.ts

@@ -36,6 +36,7 @@ declare class NgxBoxShadowComponent implements OnInit, AfterViewInit, OnDestroy,
     protected _onChange: (value: string) => void;
     protected _onTouched: () => void;
     _onValidateChange: () => void;
+    private stopDrag?;
     pad: ElementRef<HTMLDivElement>;
     thumb: ElementRef<HTMLDivElement>;
     browserService: BrowserService;
@@ -53,9 +54,7 @@ declare class NgxBoxShadowComponent implements OnInit, AfterViewInit, OnDestroy,
     private updateRects;
     private resetPosition;
     onResize(): void;
-    onDrag(ev: MouseEvent | TouchEvent): void;
     private updatePosition;
-    onDragEnd(ev: MouseEvent | TouchEvent): void;
     setValueByPosition(thumbRec: DOMRect, padRec: DOMRect): void;
     onChangeValue(): void;
     private convertValueToPosition;

package/types/ngx-kit-data-table.d.ts

@@ -270,6 +270,7 @@ declare class NgxTable<T extends object> implements OnInit, AfterContentInit {
     private templateMap;
     protected readonly resolvedMultiSort: _angular_core.Signal<boolean>;
     private readonly directionService;
+    private readonly destroyRef;
     protected readonly resolvedDirection: _angular_core.Signal<ngx_kit_shared.Direction>;
     constructor();
     ngOnInit(): void;

package/types/ngx-kit-date-picker.d.ts

@@ -285,7 +285,7 @@ declare class NgxInputDatePickerComponent extends NgxDatePickerBase implements C
     clear(): void;
     stopPagination(ev: Event): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgxInputDatePickerComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<NgxInputDatePickerComponent, "ngx-datepicker", never, { "setTheme": { "alias": "theme"; "required": false; }; "setConfig": { "alias": "config"; "required": false; }; "locale": { "alias": "locale"; "required": false; }; "setMin": { "alias": "min"; "required": false; }; "setMax": { "alias": "max"; "required": false; }; "view": { "alias": "view"; "required": false; }; }, { "change": "change"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<NgxInputDatePickerComponent, "ngx-date-picker", never, { "setTheme": { "alias": "theme"; "required": false; }; "setConfig": { "alias": "config"; "required": false; }; "locale": { "alias": "locale"; "required": false; }; "setMin": { "alias": "min"; "required": false; }; "setMax": { "alias": "max"; "required": false; }; "view": { "alias": "view"; "required": false; }; }, { "change": "change"; }, never, never, true, never>;
 }
 
 declare function provideDateAdapters(...additional: DateAdapterRegistration[]): Provider[];

package/types/ngx-kit-dialog.d.ts

@@ -121,6 +121,7 @@ declare class NgxDialogBodyDirective implements AfterViewInit {
 }
 
 declare class NgxDialogModule {
+    private readonly platformId;
     constructor(parentModule: NgxDialogModule | null, service: NgxOverlayService);
     static ɵfac: i0.ɵɵFactoryDeclaration<NgxDialogModule, [{ optional: true; skipSelf: true; }, null]>;
     static ɵmod: i0.ɵɵNgModuleDeclaration<NgxDialogModule, [typeof NgxDialogComponent, typeof NgxDialogHeaderDirective, typeof NgxDialogFooterDirective, typeof NgxDialogBodyDirective], [typeof i5.CommonModule], [typeof NgxDialogComponent, typeof NgxDialogHeaderDirective, typeof NgxDialogFooterDirective, typeof NgxDialogBodyDirective]>;

package/types/ngx-kit-drawer-menu.d.ts

@@ -0,0 +1,101 @@
+import * as _angular_core from '@angular/core';
+
+/**
+ * از 'start'/'end' منطقی استفاده می‌کنیم نه 'left'/'right' — یعنی توی
+ * RTL خودکار برعکس می‌شه (start یعنی راست در RTL، چپ در LTR)، دقیقاً هماهنگ
+ * با بقیه‌ی کتابخونه که همه‌جا از پراپرتی‌های منطقیِ CSS استفاده می‌کنه.
+ */
+type NgxDrawerSide = 'start' | 'end';
+/**
+ * جلوه‌ی بازوبسته‌شدنِ خودِ پنل:
+ *  - slide: اسلاید ساده‌ی کلاسیک
+ *  - curtain: چند نوار عمودیِ هم‌رنگِ پنل که با تأخیرِ پلکانی جمع می‌شن و
+ *    محتوا رو نمایان می‌کنن — حسِ باز شدنِ یه پرده‌ی چندلَته
+ *  - jelly: بازشدن با افکتِ ژله‌ای/کشسان — چند نوسانِ فنری که رفته‌رفته
+ *    فروکش می‌کنه (الهام از https://dribbble.com/shots/2307371)
+ *  - pull: یه کشیدگیِ لاستیکیِ تک‌ضربه‌ای — لبه‌ی پنل از اندازه‌ی نهایی رد
+ *    می‌شه و برمی‌گرده سرجاش (rubber-band)
+ *  - rotate3d: چرخشِ سه‌بعدیِ دور لولا (مثل باز شدنِ یه در)، با perspective
+ *  - flip3d: پنل و محتوای صفحه با هم مثل ورق‌زدنِ یه کتاب می‌چرخن
+ *  - scale: بزرگ‌شدن از مرکز همراه با fade
+ */
+type NgxDrawerEffect = 'slide' | 'curtain' | 'jelly' | 'pull' | 'rotate3d' | 'flip3d' | 'scale';
+/**
+ * رفتار محتوای اصلیِ صفحه وقتی درور باز می‌شه:
+ *  - overlay: محتوا سرجاش می‌مونه، درور روش شناور می‌شه (با بک‌دراپ)
+ *  - push: محتوا به‌اندازه‌ی عرضِ درور هل داده می‌شه (کنار می‌ره)
+ *  - reveal: محتوا کمی کوچیک/عقب می‌ره، انگار درور از زیرش نمایان می‌شه
+ *    (همون افکت معروف iOS)
+ */
+type NgxDrawerContentBehavior = 'overlay' | 'push' | 'reveal';
+
+/**
+ * درور منو (side drawer) با ۶ جلوه‌ی بازوبسته‌شدنِ متفاوت (از ساده تا
+ * سه‌بعدی/ژله‌ای) و ۳ رفتار برای محتوای صفحه (overlay/push/reveal) —
+ * دقیقاً مدل کتابخونه‌های حرفه‌ای مثل react-burger-menu یا Ionic Menu، ولی
+ * signal-based و بدون هیچ وابستگی خارجی.
+ *
+ * نکات معماری:
+ *  - از 'start'/'end' منطقی استفاده می‌کنه، پس با CSS logical properties
+ *    زیر RTL خودکار برعکس می‌شه؛ فقط ریاضیِ درگ (که برخلاف CSS جهت فیزیکیِ
+ *    واقعی لازم داره) از DirectionService مشترک استفاده می‌کنه.
+ *  - وضعیت باز/بسته با model() دوطرفه‌ست، پس هم با [(open)] قابل کنترله و
+ *    هم می‌تونه به‌صورت خودکار و زنده با عرض صفحه هماهنگ بشه (respondToViewport)
+ *    — یعنی رد شدن از breakpoint (نه فقط بار اول لود) می‌تونه خودکار باز/بسته‌ش کنه.
+ *  - افکت‌های jelly/pull با keyframe سه‌مرحله‌ای (overshoot → نوسان → استقرار)
+ *    پیاده شدن، نه فقط یه transition ساده.
+ */
+declare class NgxDrawerMenuComponent {
+    side: _angular_core.InputSignal<NgxDrawerSide>;
+    effect: _angular_core.InputSignal<NgxDrawerEffect>;
+    contentBehavior: _angular_core.InputSignal<NgxDrawerContentBehavior>;
+    width: _angular_core.InputSignal<number>;
+    swipeEdgeSize: _angular_core.InputSignal<number>;
+    curtainStrips: _angular_core.InputSignal<number>;
+    backdropClose: _angular_core.InputSignal<boolean>;
+    swipeEnabled: _angular_core.InputSignal<boolean>;
+    /** اگه true باشه، رد شدن از mobileBreakpoint به‌صورت زنده open رو با openOnDesktop/openOnMobile هماهنگ می‌کنه */
+    respondToViewport: _angular_core.InputSignal<boolean>;
+    openOnDesktop: _angular_core.InputSignal<boolean>;
+    openOnMobile: _angular_core.InputSignal<boolean>;
+    mobileBreakpoint: _angular_core.InputSignal<number>;
+    /** state دوطرفه‌ی باز/بسته؛ با [(open)] قابل bind هست */
+    open: _angular_core.ModelSignal<boolean>;
+    private readonly directionService;
+    private readonly doc;
+    private readonly destroyRef;
+    /** فقط حین یه درگِ واقعی مقدار داره؛ null یعنی از روی open() تصمیم بگیر */
+    protected readonly dragRatio: _angular_core.WritableSignal<number | null>;
+    protected readonly isDragging: _angular_core.Signal<boolean>;
+    protected readonly visualOpen: _angular_core.Signal<number>;
+    protected readonly strips: _angular_core.Signal<number[]>;
+    /**
+     * +۱ یعنی این پنل فیزیکاً روی لبه‌ی چپِ صفحه‌ست، -۱ یعنی لبه‌ی راست —
+     * برای transform:translateX() محتوای اصلی (که برخلاف inset-inline، به
+     * dir=rtl خودکار واکنش نشون نمی‌ده) لازمه. reactive هست چون هم به side()
+     * و هم به جهتِ زنده‌ی صفحه (directionService.isRtl()) وابسته‌ست.
+     */
+    protected readonly pushDirSign: _angular_core.Signal<1 | -1>;
+    /** برای افکت‌های keyframe‌محور (jelly/pull) — فقط لحظه‌ی رهاشدن (نه حین درگ زنده) پخش می‌شه */
+    protected readonly playEffectClass: _angular_core.WritableSignal<boolean>;
+    private stopDrag?;
+    private dragStartX;
+    private dragStartRatio;
+    private prevOpen;
+    constructor();
+    protected onEscape(): void;
+    protected closeFromBackdrop(): void;
+    toggle(): void;
+    /** true یعنی این پنل فیزیکاً روی لبه‌ی چپِ صفحه‌ست (صرف‌نظر از start/end منطقی) */
+    private isPhysicalLeftEdge;
+    protected stripDelay(index: number): string;
+    protected onEdgeDragStart(ev: MouseEvent | TouchEvent): void;
+    protected onPanelDragStart(ev: MouseEvent | TouchEvent): void;
+    private beginDrag;
+    private clientXOf;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxDrawerMenuComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxDrawerMenuComponent, "ngx-drawer-menu", never, { "side": { "alias": "side"; "required": false; "isSignal": true; }; "effect": { "alias": "effect"; "required": false; "isSignal": true; }; "contentBehavior": { "alias": "contentBehavior"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "swipeEdgeSize": { "alias": "swipeEdgeSize"; "required": false; "isSignal": true; }; "curtainStrips": { "alias": "curtainStrips"; "required": false; "isSignal": true; }; "backdropClose": { "alias": "backdropClose"; "required": false; "isSignal": true; }; "swipeEnabled": { "alias": "swipeEnabled"; "required": false; "isSignal": true; }; "respondToViewport": { "alias": "respondToViewport"; "required": false; "isSignal": true; }; "openOnDesktop": { "alias": "openOnDesktop"; "required": false; "isSignal": true; }; "openOnMobile": { "alias": "openOnMobile"; "required": false; "isSignal": true; }; "mobileBreakpoint": { "alias": "mobileBreakpoint"; "required": false; "isSignal": true; }; "open": { "alias": "open"; "required": false; "isSignal": true; }; }, { "open": "openChange"; }, never, ["*", "[drawerContent]"], true, never>;
+}
+
+export { NgxDrawerMenuComponent };
+export type { NgxDrawerContentBehavior, NgxDrawerEffect, NgxDrawerSide };

package/types/ngx-kit-dropzone.d.ts

@@ -0,0 +1,84 @@
+import * as _angular_core from '@angular/core';
+import { OnDestroy } from '@angular/core';
+
+interface NgxDropzoneFile {
+    /** شناسه‌ی یکتا برای track کردن توی @for و امکان حذف تکی */
+    id: string;
+    file: File;
+    /** فقط برای فایل‌های تصویری پر می‌شه (object URL) */
+    previewUrl?: string;
+    status: 'pending' | 'accepted' | 'rejected';
+    /** در صورت رد شدن، دلیلش */
+    rejectionReason?: NgxDropzoneRejectionReason;
+}
+type NgxDropzoneRejectionReason = 'type' | 'size' | 'count';
+interface NgxDropzoneRejectedFile {
+    file: File;
+    reason: NgxDropzoneRejectionReason;
+}
+
+/**
+ * ناحیه‌ی درگ‌اند‌دراپِ فایل — کاملاً مستقل (بدون وابستگی به هیچ lib
+ * دیگه‌ای، حتی shared)، signal-based و OnPush.
+ *
+ * ویژگی‌های مهمی که معمولاً پیاده‌سازی‌های ساده‌ی dropzone ندارن:
+ *  - شمارنده‌ی dragenter/dragleave: چون dragleave برای فرزندهای داخل
+ *    dropzone هم شلیک می‌شه، پیاده‌سازی‌های ساده موقع درگ‌کردن روی متن/آیکون
+ *    داخل ناحیه، حالت "درگ" رو اشتباهی خاموش می‌کنن (چشمک‌زدن). این‌جا با
+ *    شمارنده حل شده.
+ *  - پیمایش بازگشتیِ پوشه‌ها (وقتی کاربر یه پوشه رو درگ کنه، نه فقط فایل).
+ *  - قابل‌دسترسی با کیبورد (focusable + Enter/Space).
+ *  - پاک‌سازی object URL پیش‌نمایش‌ها روی حذف/destroy (وگرنه نشتی حافظه‌ست).
+ */
+declare class NgxDropzoneComponent implements OnDestroy {
+    /** الگوی accept مثل input[type=file]: "image/*", ".pdf,.docx" و ... */
+    accept: _angular_core.InputSignal<string>;
+    multiple: _angular_core.InputSignal<boolean>;
+    /** حداکثر حجم هر فایل به بایت؛ undefined یعنی بدون محدودیت */
+    maxFileSize: _angular_core.InputSignal<number | undefined>;
+    /** حداکثر تعداد فایل مجاز؛ undefined یعنی بدون محدودیت */
+    maxFiles: _angular_core.InputSignal<number | undefined>;
+    disabled: _angular_core.InputSignal<boolean>;
+    /** نمایش لیست/پیش‌نمایش فایل‌های انتخاب‌شده داخل خودِ کامپوننت */
+    showFileList: _angular_core.InputSignal<boolean>;
+    filesAdded: _angular_core.OutputEmitterRef<File[]>;
+    filesRejected: _angular_core.OutputEmitterRef<NgxDropzoneRejectedFile[]>;
+    /** کل لیست فعلی (بعد از هر تغییر) — برای binding راحت‌تر */
+    filesChange: _angular_core.OutputEmitterRef<File[]>;
+    protected readonly files: _angular_core.WritableSignal<NgxDropzoneFile[]>;
+    protected readonly isDragging: _angular_core.WritableSignal<boolean>;
+    private dragCounter;
+    private readonly fileInput;
+    protected readonly hint: _angular_core.Signal<string>;
+    protected formatSize(bytes: number): string;
+    ngOnDestroy(): void;
+    protected onDragEnter(ev: DragEvent): void;
+    protected onDragOver(ev: DragEvent): void;
+    protected onDragLeave(ev: DragEvent): void;
+    protected onDrop(ev: DragEvent): Promise<void>;
+    protected onBrowseClick(): void;
+    protected onKeydown(ev: KeyboardEvent): void;
+    protected onFileInputChange(ev: Event): void;
+    protected removeFile(id: string): void;
+    private handleIncomingFiles;
+    private emitCurrentFiles;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxDropzoneComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxDropzoneComponent, "ngx-dropzone", never, { "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "maxFileSize": { "alias": "maxFileSize"; "required": false; "isSignal": true; }; "maxFiles": { "alias": "maxFiles"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "showFileList": { "alias": "showFileList"; "required": false; "isSignal": true; }; }, { "filesAdded": "filesAdded"; "filesRejected": "filesRejected"; "filesChange": "filesChange"; }, never, ["[dropzone-icon]", "*"], true, never>;
+}
+
+/**
+ * چک می‌کنه یه فایل با pattern رشته‌ای accept (مثل input[type=file])
+ * مطابقت داره یا نه. پشتیبانی می‌شه از:
+ *  - MIME کامل: "image/png"
+ *  - MIME با wildcard: "image/*"
+ *  - پسوند فایل: ".png", ".jpg"
+ *  - لیست کاما-جدا از موارد بالا: "image/*,.pdf,.docx"
+ */
+declare function matchesAccept(file: File, accept?: string): boolean;
+/** تبدیل بایت به یه رشته‌ی خوانا (KB/MB/GB) */
+declare function formatBytes(bytes: number): string;
+/** استخراج فایل‌های واقعی از یک DataTransfer، شامل پیمایش بازگشتیِ پوشه‌ها (وقتی مرورگر پشتیبانی کنه) */
+declare function extractFilesFromDataTransfer(dataTransfer: DataTransfer): Promise<File[]>;
+
+export { NgxDropzoneComponent, extractFilesFromDataTransfer, formatBytes, matchesAccept };
+export type { NgxDropzoneFile, NgxDropzoneRejectedFile, NgxDropzoneRejectionReason };

package/types/ngx-kit-form-field.d.ts

@@ -0,0 +1,31 @@
+import * as _angular_core from '@angular/core';
+
+type NgxFormFieldType = 'text' | 'password' | 'email' | 'number' | 'tel' | 'url' | 'search' | 'textarea';
+
+declare class NgxFormField {
+    readonly value: _angular_core.ModelSignal<string | number>;
+    readonly label: _angular_core.InputSignal<string>;
+    readonly type: _angular_core.InputSignal<NgxFormFieldType>;
+    readonly placeholder: _angular_core.InputSignal<string>;
+    readonly required: _angular_core.InputSignal<boolean>;
+    readonly disabled: _angular_core.InputSignal<boolean>;
+    readonly readonly: _angular_core.InputSignal<boolean>;
+    readonly float: _angular_core.InputSignal<boolean>;
+    readonly name: _angular_core.InputSignal<string | null>;
+    readonly autocomplete: _angular_core.InputSignal<string | null>;
+    readonly rows: _angular_core.InputSignal<number>;
+    readonly hint: _angular_core.InputSignal<string>;
+    readonly errorMessages: _angular_core.InputSignal<string[]>;
+    readonly dir: _angular_core.InputSignal<"" | "ltr" | "rtl">;
+    readonly id: _angular_core.InputSignal<string>;
+    readonly focused: _angular_core.OutputEmitterRef<void>;
+    readonly blurred: _angular_core.OutputEmitterRef<void>;
+    readonly hasValue: _angular_core.Signal<boolean>;
+    onInput(event: Event): void;
+    onFocus(): void;
+    onBlur(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxFormField, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxFormField, "ngx-form-field", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": true; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "float": { "alias": "float"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "autocomplete": { "alias": "autocomplete"; "required": false; "isSignal": true; }; "rows": { "alias": "rows"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "errorMessages": { "alias": "errorMessages"; "required": false; "isSignal": true; }; "dir": { "alias": "dir"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "focused": "focused"; "blurred": "blurred"; }, never, never, true, never>;
+}
+
+export { NgxFormField };

package/types/ngx-kit-gallery.d.ts

@@ -0,0 +1,168 @@
+import * as _angular_core from '@angular/core';
+
+interface NgxImageViewerItem {
+    src: string;
+    alt?: string;
+    caption?: string;
+    /** نام فایل هنگام دانلود؛ نبود یعنی از روی src حدس زده می‌شه */
+    downloadFileName?: string;
+}
+/**
+ * هر دکمه‌ی نوار ابزار جدا فعال/غیرفعال می‌شه — دقیقاً طبق خواسته: «این
+ * دکمه‌های کانفیگی باشه که هر کدوم خواست فعال کنه».
+ */
+interface NgxImageViewerToolbarConfig {
+    prevNext?: boolean;
+    counter?: boolean;
+    zoomIn?: boolean;
+    zoomOut?: boolean;
+    resetZoom?: boolean;
+    rotateLeft?: boolean;
+    rotateRight?: boolean;
+    download?: boolean;
+    print?: boolean;
+    fullscreen?: boolean;
+    close?: boolean;
+}
+declare const NGX_IMAGE_VIEWER_DEFAULT_TOOLBAR: Required<NgxImageViewerToolbarConfig>;
+
+/**
+ * ویوئر حرفه‌ایِ تصویر: یه لیست تصویر می‌گیره، اولی رو نشون می‌ده، با
+ * دکمه‌های چپ/راست (مثل کاروسل) بین‌شون می‌ره، و یه نوار ابزار کاملاً
+ * قابل‌تنظیم (هر دکمه جدا فعال/غیرفعال می‌شه) داره: زوم این/اوت/ریست،
+ * چرخش، دانلود، پرینت، تمام‌صفحه.
+ *
+ * تعامل‌ها:
+ *  - اسکرول موس روی تصویر = زوم (نسبت به همون نقطه‌ی زیر cursor، نه مرکز)
+ *  - دو انگشتی روی تاچ = پینچ زوم
+ *  - وقتی زوم‌شده، درگ با موس یا تک‌انگشتی = پن
+ *  - کیبورد: ← → برای قبلی/بعدی، +/- برای زوم، Esc برای closed
+ *
+ * چون wheel/touchmove باید preventDefault بشن (وگرنه صفحه اسکرول/زوم
+ * می‌شه) و انگیولار این ایونت‌ها رو به‌صورت پیش‌فرض passive رجیستر می‌کنه
+ * (که توش preventDefault اثر نداره)، این‌ها با addEventListener دستی و
+ * {passive:false} وصل می‌شن، نه با بایندینگ تمپلیت.
+ *
+ * می‌تونه هم مستقیم توی صفحه جا بگیره، هم توسط مصرف‌کننده داخل
+ * ngx-kit/dialog (یا هر overlay دیگه) قرار بگیره — خودش به هیچ‌کدوم وابسته
+ * نیست، فقط با closed خروجی به بیرون خبر می‌ده که «ببندم».
+ */
+declare class NgxImageViewerComponent {
+    images: _angular_core.InputSignal<NgxImageViewerItem[]>;
+    startIndex: _angular_core.InputSignal<number>;
+    toolbar: _angular_core.InputSignal<NgxImageViewerToolbarConfig>;
+    minZoom: _angular_core.InputSignal<number>;
+    maxZoom: _angular_core.InputSignal<number>;
+    zoomStep: _angular_core.InputSignal<number>;
+    indexChange: _angular_core.OutputEmitterRef<number>;
+    closed: _angular_core.OutputEmitterRef<void>;
+    protected readonly activeIndex: _angular_core.WritableSignal<number>;
+    protected readonly zoom: _angular_core.WritableSignal<number>;
+    protected readonly panX: _angular_core.WritableSignal<number>;
+    protected readonly panY: _angular_core.WritableSignal<number>;
+    protected readonly rotation: _angular_core.WritableSignal<number>;
+    protected readonly activeImage: _angular_core.Signal<NgxImageViewerItem | undefined>;
+    protected readonly toolbarConfig: _angular_core.Signal<{
+        prevNext: boolean;
+        counter: boolean;
+        zoomIn: boolean;
+        zoomOut: boolean;
+        resetZoom: boolean;
+        rotateLeft: boolean;
+        rotateRight: boolean;
+        download: boolean;
+        print: boolean;
+        fullscreen: boolean;
+        close: boolean;
+    }>;
+    protected readonly isZoomed: _angular_core.Signal<boolean>;
+    protected readonly stageTransform: _angular_core.Signal<string>;
+    private readonly stageEl;
+    private readonly hostElRef;
+    private readonly destroyRef;
+    private pinchStartDistance;
+    private pinchStartZoom;
+    private stopPanDrag?;
+    constructor();
+    protected onKeydown(ev: KeyboardEvent): void;
+    protected next(): void;
+    protected prev(): void;
+    protected goTo(index: number): void;
+    protected zoomIn(): void;
+    protected zoomOut(): void;
+    protected resetView(): void;
+    protected rotateLeft(): void;
+    protected rotateRight(): void;
+    protected download(): Promise<void>;
+    protected print(): void;
+    protected toggleFullscreen(): void;
+    protected close(): void;
+    protected onPanPointerDown(ev: MouseEvent): void;
+    private beginPanDrag;
+    private setZoomAtCenter;
+    private applyZoomAt;
+    private clientXOf;
+    private clientYOf;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxImageViewerComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxImageViewerComponent, "ngx-image-viewer", never, { "images": { "alias": "images"; "required": true; "isSignal": true; }; "startIndex": { "alias": "startIndex"; "required": false; "isSignal": true; }; "toolbar": { "alias": "toolbar"; "required": false; "isSignal": true; }; "minZoom": { "alias": "minZoom"; "required": false; "isSignal": true; }; "maxZoom": { "alias": "maxZoom"; "required": false; "isSignal": true; }; "zoomStep": { "alias": "zoomStep"; "required": false; "isSignal": true; }; }, { "indexChange": "indexChange"; "closed": "closed"; }, never, never, true, never>;
+}
+
+interface NgxImageViewerOpenOptions {
+    startIndex?: number;
+    toolbar?: NgxImageViewerToolbarConfig;
+    minZoom?: number;
+    maxZoom?: number;
+    zoomStep?: number;
+}
+/**
+ * راه میان‌بر برای وقتی که کاربر می‌خواد ویوئر رو داخل یه دیالوگِ تمام‌صفحه
+ * باز کنه، بدون این‌که خودش دستی wire کنه. اگه کسی می‌خواد داخل دیالوگِ
+ * خودش (مثلاً ngx-kit/dialog) بذارتش، کافیه مستقیم از NgxImageViewerComponent
+ * استفاده کنه — این سرویس صرفاً یه میان‌بَره، وابستگی اجباری نیست.
+ *
+ * دقیقاً همون الگوی امن‌شده‌ی NgxMessageService: با Map<id, ComponentRef> و
+ * detachView قبل از destroy، تا اون نشتی حافظه‌ای که قبلاً توی message
+ * service پیدا و رفع شد، اینجا از اول تکرار نشه.
+ */
+declare class NgxImageViewerService {
+    private readonly appRef;
+    private readonly envInjector;
+    private nextId;
+    private readonly openInstances;
+    open(images: NgxImageViewerItem[], options?: NgxImageViewerOpenOptions): {
+        close: () => void;
+    };
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxImageViewerService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NgxImageViewerService>;
+}
+
+interface PanZoomState {
+    zoom: number;
+    panX: number;
+    panY: number;
+}
+/**
+ * با تغییر zoom، pan رو طوری تنظیم می‌کنه که نقطه‌ی زیر cursor/انگشت‌ها
+ * (نسبت به مرکز کانتینر) سرجاش بمونه — یعنی zoom-to-cursor به‌جای
+ * zoom-to-center (که تجربه‌ی خیلی بهتری داره، دقیقاً مثل هر ویوئر حرفه‌ای).
+ *
+ * ریاضیِ پشتش: با transform="translate(panX,panY) scale(zoom)"، موقعیتِ
+ * صفحه‌ایِ یه نقطه‌ی محلیِ p (نسبت به مرکز) برابره با
+ * center + pan + p*zoom. اول p رو از روی وضعیت فعلی حساب می‌کنیم، بعد pan
+ * جدید رو طوری می‌سازیم که با zoom تازه، همون p به همون مختصات صفحه برسه.
+ */
+declare function zoomAroundPoint(current: PanZoomState, newZoom: number, cursorX: number, cursorY: number, containerWidth: number, containerHeight: number): PanZoomState;
+declare function distanceBetweenTouches(a: Touch, b: Touch): number;
+declare function midpointOfTouches(a: Touch, b: Touch): {
+    x: number;
+    y: number;
+};
+declare function clamp(value: number, min: number, max: number): number;
+
+/** دانلود تصویر با fetch→blob (نام‌گذاریِ درست فایل رو تضمین می‌کنه)؛ اگه CORS اجازه نداد، در تب جدید باز می‌شه */
+declare function downloadImage(src: string, filename?: string): Promise<void>;
+/** یه پنجره‌ی جدید فقط با همون تصویر باز می‌کنه و بعد از لود، print می‌زنه؛ با DOM API (نه innerHTML) پس در برابر src مخرب امنه */
+declare function printImage(src: string): void;
+
+export { NGX_IMAGE_VIEWER_DEFAULT_TOOLBAR, NgxImageViewerComponent, NgxImageViewerService, clamp, distanceBetweenTouches, downloadImage, midpointOfTouches, printImage, zoomAroundPoint };
+export type { NgxImageViewerItem, NgxImageViewerOpenOptions, NgxImageViewerToolbarConfig, PanZoomState };