ngx-kit 6.0.2 → 6.2.0

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

@@ -1,13 +1,22 @@
 import * as _angular_core from '@angular/core';
-import { OnDestroy } from '@angular/core';
+import { OnDestroy, InjectionToken } from '@angular/core';
+import { HttpHeaders } from '@angular/common/http';
+import { Observable } from 'rxjs';
 
-interface NgxDropzoneFile {
+type NgxDropzoneFileStatus = 'pending' | 'accepted' | 'uploading' | 'uploaded' | 'error' | 'canceled';
+interface NgxDropzoneFile<TResponse = any> {
     /** شناسه‌ی یکتا برای track کردن توی @for و امکان حذف تکی */
     id: string;
     file: File;
     /** فقط برای فایل‌های تصویری پر می‌شه (object URL) */
     previewUrl?: string;
-    status: 'pending' | 'accepted' | 'rejected';
+    status: NgxDropzoneFileStatus;
+    /** Upload progress, from 0 to 100. */
+    progress: number;
+    /** Response returned by the upload adapter. */
+    response?: TResponse;
+    /** Upload error, if the request failed. */
+    error?: any;
     /** در صورت رد شدن، دلیلش */
     rejectionReason?: NgxDropzoneRejectionReason;
 }
@@ -17,19 +26,57 @@ interface NgxDropzoneRejectedFile {
     reason: NgxDropzoneRejectionReason;
 }
 
+interface NgxDropzoneUploadRequest {
+    /** Target endpoint. */
+    url: string;
+    /** Multipart form field name used for the file. */
+    alias: string;
+    file: File;
+    /** Optional additional multipart fields. */
+    data?: Record<string, string | Blob | number | boolean>;
+    /** Optional request headers. */
+    headers?: HttpHeaders | Record<string, string | string[]>;
+    /** Send cookies/auth information for cross-origin requests. */
+    withCredentials?: boolean;
+}
+type NgxDropzoneUploadEvent<TResponse = unknown> = {
+    type: 'progress';
+    loaded: number;
+    total?: number;
+    percent: number;
+} | {
+    type: 'response';
+    response: TResponse;
+    status: number;
+    headers?: HttpHeaders;
+};
 /**
- * ناحیه‌ی درگ‌اند‌دراپِ فایل — کاملاً مستقل (بدون وابستگی به هیچ lib
- * دیگه‌ای، حتی shared)، signal-based و OnPush.
+ * Upload adapter used by ngx-dropzone.
  *
- * ویژگی‌های مهمی که معمولاً پیاده‌سازی‌های ساده‌ی dropzone ندارن:
- *  - شمارنده‌ی dragenter/dragleave: چون dragleave برای فرزندهای داخل
- *    dropzone هم شلیک می‌شه، پیاده‌سازی‌های ساده موقع درگ‌کردن روی متن/آیکون
- *    داخل ناحیه، حالت "درگ" رو اشتباهی خاموش می‌کنن (چشمک‌زدن). این‌جا با
- *    شمارنده حل شده.
- *  - پیمایش بازگشتیِ پوشه‌ها (وقتی کاربر یه پوشه رو درگ کنه، نه فقط فایل).
- *  - قابل‌دسترسی با کیبورد (focusable + Enter/Space).
- *  - پاک‌سازی object URL پیش‌نمایش‌ها روی حذف/destroy (وگرنه نشتی حافظه‌ست).
+ * Implement this interface when the default HttpClient implementation is not
+ * suitable (for example, when the host application uses Axios, fetch, tus,
+ * S3 multipart upload, etc.).
+ */
+interface NgxDropzoneUploadService {
+    upload<TResponse = unknown>(request: NgxDropzoneUploadRequest): Observable<NgxDropzoneUploadEvent<TResponse>>;
+}
+interface NgxDropzoneUploadProgressEvent {
+    item: NgxDropzoneFileLike;
+    loaded: number;
+    total?: number;
+    percent: number;
+}
+/**
+ * Deliberately small structural type so consumers do not have to depend on a
+ * concrete response type.
  */
+interface NgxDropzoneFileLike {
+    id: string;
+    file: File;
+    progress: number;
+}
+
+type NgxDropzoneUploadMode = 'all' | 'single';
 declare class NgxDropzoneComponent implements OnDestroy {
     /** الگوی accept مثل input[type=file]: "image/*", ".pdf,.docx" و ... */
     accept: _angular_core.InputSignal<string>;
@@ -41,16 +88,55 @@ declare class NgxDropzoneComponent implements OnDestroy {
     disabled: _angular_core.InputSignal<boolean>;
     /** نمایش لیست/پیش‌نمایش فایل‌های انتخاب‌شده داخل خودِ کامپوننت */
     showFileList: _angular_core.InputSignal<boolean>;
+    /** Upload endpoint. */
+    uploadUrl: _angular_core.InputSignal<string>;
+    /** Multipart form-data field name. */
+    uploadAlias: _angular_core.InputSignal<string>;
+    /** Automatically enqueue newly accepted files for upload. */
+    autoUpload: _angular_core.InputSignal<boolean>;
+    /** Maximum number of simultaneous uploads. */
+    maxParallel: _angular_core.InputSignal<number>;
+    /**
+     * Manual upload behavior:
+     * - all: one "Upload all" action uploads all pending files.
+     * - single: every pending row gets its own Upload button.
+     */
+    uploadMode: _angular_core.InputSignal<NgxDropzoneUploadMode>;
+    /** Extra multipart form fields sent with every file. */
+    uploadData: _angular_core.InputSignal<Record<string, string | number | boolean | Blob>>;
+    /** Optional request headers. */
+    uploadHeaders: _angular_core.InputSignal<Record<string, string | string[]>>;
+    /** Send credentials/cookies with the upload request. */
+    uploadWithCredentials: _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[]>;
+    /** Emitted when an individual upload starts. */
+    uploadStarted: _angular_core.OutputEmitterRef<NgxDropzoneFile<any>>;
+    /** Emitted for every upload progress update. */
+    uploadProgress: _angular_core.OutputEmitterRef<NgxDropzoneUploadProgressEvent>;
+    /** Emitted after a file is successfully uploaded. */
+    uploadSuccess: _angular_core.OutputEmitterRef<NgxDropzoneFile<any>>;
+    /** Emitted when an upload fails. */
+    uploadError: _angular_core.OutputEmitterRef<{
+        item: NgxDropzoneFile;
+        error: unknown;
+    }>;
+    protected readonly files: _angular_core.WritableSignal<NgxDropzoneFile<any>[]>;
     protected readonly isDragging: _angular_core.WritableSignal<boolean>;
     private dragCounter;
+    private readonly uploadService;
     private readonly fileInput;
+    private readonly uploadSubscriptions;
+    private readonly uploadQueue;
+    private activeUploads;
+    private readonly activeUploadIds;
+    protected readonly pendingCount: _angular_core.Signal<number>;
+    protected readonly hasUploadConfiguration: _angular_core.Signal<boolean>;
     protected readonly hint: _angular_core.Signal<string>;
     protected formatSize(bytes: number): string;
+    protected isPending(item: NgxDropzoneFile): boolean;
+    protected trackById(_index: number, item: NgxDropzoneFile): string;
     ngOnDestroy(): void;
     protected onDragEnter(ev: DragEvent): void;
     protected onDragOver(ev: DragEvent): void;
@@ -60,12 +146,37 @@ declare class NgxDropzoneComponent implements OnDestroy {
     protected onKeydown(ev: KeyboardEvent): void;
     protected onFileInputChange(ev: Event): void;
     protected removeFile(id: string): void;
+    protected uploadAll(): void;
+    protected uploadSingle(id: string): void;
+    protected retryUpload(id: string): void;
     private handleIncomingFiles;
+    private enqueueUploads;
+    private pumpQueue;
+    private startUpload;
+    private markUploadError;
+    private finishUpload;
+    private updateFile;
     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>;
+    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; }; "uploadUrl": { "alias": "uploadUrl"; "required": false; "isSignal": true; }; "uploadAlias": { "alias": "uploadAlias"; "required": false; "isSignal": true; }; "autoUpload": { "alias": "autoUpload"; "required": false; "isSignal": true; }; "maxParallel": { "alias": "maxParallel"; "required": false; "isSignal": true; }; "uploadMode": { "alias": "uploadMode"; "required": false; "isSignal": true; }; "uploadData": { "alias": "uploadData"; "required": false; "isSignal": true; }; "uploadHeaders": { "alias": "uploadHeaders"; "required": false; "isSignal": true; }; "uploadWithCredentials": { "alias": "uploadWithCredentials"; "required": false; "isSignal": true; }; }, { "filesAdded": "filesAdded"; "filesRejected": "filesRejected"; "filesChange": "filesChange"; "uploadStarted": "uploadStarted"; "uploadProgress": "uploadProgress"; "uploadSuccess": "uploadSuccess"; "uploadError": "uploadError"; }, never, ["[dropzone-icon]", "*"], true, never>;
+}
+
+declare class NgxDropzoneHttpUploadService implements NgxDropzoneUploadService {
+    private readonly http;
+    upload<TResponse = unknown>(request: NgxDropzoneUploadRequest): Observable<NgxDropzoneUploadEvent<TResponse>>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxDropzoneHttpUploadService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NgxDropzoneHttpUploadService>;
 }
 
+/**
+ * Upload adapter used by ngx-dropzone.
+ *
+ * Default: Angular HttpClient.
+ * Override this token at application/component level to use Axios or any
+ * other upload implementation.
+ */
+declare const NGX_DROPZONE_UPLOAD_SERVICE: InjectionToken<NgxDropzoneUploadService>;
+
 /**
  * چک می‌کنه یه فایل با pattern رشته‌ای accept (مثل input[type=file])
  * مطابقت داره یا نه. پشتیبانی می‌شه از:
@@ -80,5 +191,5 @@ declare function formatBytes(bytes: number): string;
 /** استخراج فایل‌های واقعی از یک DataTransfer، شامل پیمایش بازگشتیِ پوشه‌ها (وقتی مرورگر پشتیبانی کنه) */
 declare function extractFilesFromDataTransfer(dataTransfer: DataTransfer): Promise<File[]>;
 
-export { NgxDropzoneComponent, extractFilesFromDataTransfer, formatBytes, matchesAccept };
-export type { NgxDropzoneFile, NgxDropzoneRejectedFile, NgxDropzoneRejectionReason };
+export { NGX_DROPZONE_UPLOAD_SERVICE, NgxDropzoneComponent, NgxDropzoneHttpUploadService, extractFilesFromDataTransfer, formatBytes, matchesAccept };
+export type { NgxDropzoneFile, NgxDropzoneFileLike, NgxDropzoneFileStatus, NgxDropzoneRejectedFile, NgxDropzoneRejectionReason, NgxDropzoneUploadEvent, NgxDropzoneUploadMode, NgxDropzoneUploadProgressEvent, NgxDropzoneUploadRequest, NgxDropzoneUploadService };

package/types/ngx-kit-image-editor.d.ts

@@ -1,4 +1,5 @@
 import * as _angular_core from '@angular/core';
+import { InjectionToken } from '@angular/core';
 
 interface NgxCropRect {
     /** همه به پیکسل‌های واقعیِ تصویر مبدأ (نه پیکسل صفحه) */
@@ -53,6 +54,27 @@ declare class NgxPointerDragDirective {
 }
 
 type Corner = 'nw' | 'ne' | 'sw' | 'se';
+
+declare const NGX_IMAGE_EDITOR_LOCALIZATION: InjectionToken<NgxImageEditorLocalization>;
+declare class NgxImageEditorLocalization {
+    LoadingImage: string;
+    Rotation: string;
+    Brightness: string;
+    Contrast: string;
+    Saturation: string;
+    Filter: string;
+    None: string;
+    Grayscale: string;
+    Sepia: string;
+    Invert: string;
+    Cartoon: string;
+    Cancel: string;
+    Save: string;
+    Saving: string;
+    Reset: string;
+}
+declare const DEFAULT_NGX_IMAGE_EDITOR_LOCALIZATION: NgxImageEditorLocalization;
+
 /**
  * ویرایشگر تصویر: کراپ + چرخش + روشنایی/کنتراست/اشباع + فیلترهای آماده
  * (سیاه‌وسفید، سپیا، معکوس، کارتونی) + فشرده‌سازی خروجی. کاملاً روی Canvas
@@ -63,6 +85,15 @@ type Corner = 'nw' | 'ne' | 'sw' | 'se';
  * (createWorkingCopy)، نه روی تصویر اصلی که ممکنه چند مگاپیکسل باشه — وگرنه
  * درگ‌کردن اسلایدرها/گوشه‌های کراپ رو کاربر حس تاخیر می‌کرد. فقط لحظه‌ی
  * save()، رندر نهایی از روی تصویر اصلیِ کامل انجام می‌شه.
+ *
+ * اندازه‌ی صحنه (stage) با panelSize کنترل می‌شه: عرض همیشه ۱۰۰٪ عرضِ
+ * والدِ کامپوننته (با ResizeObserver اندازه‌گیری می‌شه، پس با تغییر سایز
+ * صفحه/layout هم زنده هماهنگ می‌مونه)، ارتفاع دقیقاً همون چیزیه که کاربر با
+ * panelSize می‌ده. تصویر همیشه با یک مقیاسِ «contain» واقعی (هم بر اساس
+ * عرض، هم بر اساس ارتفاع — هرکدوم تنگ‌تره) جا داده می‌شه، پس کلِ تصویر
+ * همیشه در محدوده‌ی همین باکس دیده می‌شه، صرف‌نظر از اندازه‌ی واقعیِ فایل.
+ * سقفِ مقیاس هم ۱ هست، یعنی تصاویر کوچیک بزرگ‌نمایی نمی‌شن (که باعثِ محو
+ * شدن‌شون می‌شد).
  */
 declare class NgxImageEditorComponent {
     source: _angular_core.InputSignal<string | File | Blob | null>;
@@ -71,8 +102,14 @@ declare class NgxImageEditorComponent {
     outputMaxWidth: _angular_core.InputSignal<number | undefined>;
     outputMaxHeight: _angular_core.InputSignal<number | undefined>;
     outputType: _angular_core.InputSignal<"image/jpeg" | "image/png" | "image/webp">;
-    /** حداکثر عرض نمایشِ ناحیه‌ی کراپ روی صفحه (پیکسل) */
-    displayMaxWidth: _angular_core.InputSignal<number>;
+    /**
+     * کدوم فیلترها نشون داده بشن (و به چه ترتیبی). اگه ندید، هر ۵ تا نشون داده
+     * می‌شن. آرایه‌ی خالی یعنی کلِ بخشِ فیلتر مخفی بشه.
+     */
+    filters: _angular_core.InputSignal<NgxImageFilterPreset[]>;
+    quality: _angular_core.InputSignal<number>;
+    defaultLocalization: NgxImageEditorLocalization;
+    localize: _angular_core.InputSignal<NgxImageEditorLocalization>;
     saved: _angular_core.OutputEmitterRef<NgxImageEditorResult>;
     cancelled: _angular_core.OutputEmitterRef<void>;
     protected readonly loading: _angular_core.WritableSignal<boolean>;
@@ -80,16 +117,24 @@ declare class NgxImageEditorComponent {
     protected readonly loadError: _angular_core.WritableSignal<string | null>;
     private readonly originalImage;
     private readonly workingCanvas;
+    private readonly stageWrapEl;
+    /** عرضِ واقعیِ رندرشده‌ی کانتینر؛ چون عرض همیشه ۱۰۰٪ (fluid) هست، باید زنده اندازه‌گیری بشه */
+    private readonly containerWidth;
     protected readonly rotation: _angular_core.WritableSignal<number>;
     protected readonly brightness: _angular_core.WritableSignal<number>;
     protected readonly contrast: _angular_core.WritableSignal<number>;
     protected readonly saturation: _angular_core.WritableSignal<number>;
     protected readonly filterPreset: _angular_core.WritableSignal<NgxImageFilterPreset>;
-    protected readonly quality: _angular_core.WritableSignal<number>;
     protected readonly crop: _angular_core.WritableSignal<NgxCropRect>;
     protected readonly adjustments: _angular_core.Signal<NgxImageEditorAdjustments>;
+    protected readonly filterLabels: _angular_core.Signal<Record<NgxImageFilterPreset, string>>;
     /** تصویرِ (کوچیک‌شده‌یِ) چرخیده — پایه‌ی نمایش صحنه‌ی کراپ */
     protected readonly rotatedWorkingCanvas: _angular_core.Signal<HTMLCanvasElement | null>;
+    protected readonly panelSize: _angular_core.Signal<number>;
+    /**
+     * مقیاسِ «contain» واقعی: کوچیک‌ترینِ نسبتِ عرض و ارتفاع (هرکدوم تنگ‌تره)
+     * تعیین‌کننده‌ست، و سقفش هم ۱ هست تا تصاویر کوچیک بزرگ‌نمایی نشن.
+     */
     protected readonly displayScale: _angular_core.Signal<number>;
     protected readonly stageImageUrl: _angular_core.Signal<string | null>;
     protected readonly stageSize: _angular_core.Signal<{
@@ -117,7 +162,7 @@ declare class NgxImageEditorComponent {
     protected cancel(): void;
     save(): Promise<void>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxImageEditorComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxImageEditorComponent, "ngx-image-editor", never, { "source": { "alias": "source"; "required": false; "isSignal": true; }; "aspectRatio": { "alias": "aspectRatio"; "required": false; "isSignal": true; }; "outputMaxWidth": { "alias": "outputMaxWidth"; "required": false; "isSignal": true; }; "outputMaxHeight": { "alias": "outputMaxHeight"; "required": false; "isSignal": true; }; "outputType": { "alias": "outputType"; "required": false; "isSignal": true; }; "displayMaxWidth": { "alias": "displayMaxWidth"; "required": false; "isSignal": true; }; }, { "saved": "saved"; "cancelled": "cancelled"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxImageEditorComponent, "ngx-image-editor", never, { "source": { "alias": "source"; "required": false; "isSignal": true; }; "aspectRatio": { "alias": "aspectRatio"; "required": false; "isSignal": true; }; "outputMaxWidth": { "alias": "outputMaxWidth"; "required": false; "isSignal": true; }; "outputMaxHeight": { "alias": "outputMaxHeight"; "required": false; "isSignal": true; }; "outputType": { "alias": "outputType"; "required": false; "isSignal": true; }; "filters": { "alias": "filters"; "required": false; "isSignal": true; }; "quality": { "alias": "quality"; "required": false; "isSignal": true; }; "localize": { "alias": "localize"; "required": false; "isSignal": true; }; }, { "saved": "saved"; "cancelled": "cancelled"; }, never, never, true, never>;
 }
 
 /** یه File/Blob/data-URL/URL رو به یک HTMLImageElement بارگذاری‌شده تبدیل می‌کنه */
@@ -171,5 +216,5 @@ declare function applyCartoonEffect(ctx: CanvasRenderingContext2D, width: number
     edgeThreshold?: number;
 }): void;
 
-export { NgxImageEditorComponent, NgxPointerDragDirective, applyCartoonEffect, canvasToBlob, createWorkingCopy, fitWithin, loadImage, renderComposite, renderRotated };
+export { DEFAULT_NGX_IMAGE_EDITOR_LOCALIZATION, NGX_IMAGE_EDITOR_LOCALIZATION, NgxImageEditorComponent, NgxImageEditorLocalization, NgxPointerDragDirective, applyCartoonEffect, canvasToBlob, createWorkingCopy, fitWithin, loadImage, renderComposite, renderRotated };
 export type { NgxCropRect, NgxImageEditorAdjustments, NgxImageEditorResult, NgxImageFilterPreset, NgxPointerDragDelta };