@nexterajs/ui 0.0.1 → 0.1.0

package/types/nexterajs-ui-file-uploader.d.ts

@@ -1,5 +1,8 @@
 import * as _angular_core from '@angular/core';
-import { NxeValidationTarget } from '@nexterajs/ui/core';
+import { NxeValidationTarget, NxeMessageService, NxeFormControlBase, NxeMessageKey } from '@nexterajs/ui/core';
+import { HttpEvent } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { Validator, AbstractControl, ValidationErrors } from '@angular/forms';
 
 /**
  * `nxe-file-uploader` — drop-in replacement for DevExtreme `dx-file-uploader`.
@@ -13,23 +16,30 @@ import { NxeValidationTarget } from '@nexterajs/ui/core';
  * `required` rule works — invalid while no file is chosen.
  */
 declare class NxeFileUploaderComponent implements NxeValidationTarget {
+    /** Shows the per-file cancel button — except in `useForm` mode, where dx never renders one
+     *  (m_file_uploader.js `_getCancelButton` returns null for useForm before it reads this). */
     readonly allowCanceling: _angular_core.InputSignal<boolean>;
     readonly accept: _angular_core.InputSignal<string>;
-    readonly labelText: _angular_core.InputSignal<string>;
-    readonly selectButtonText: _angular_core.InputSignal<string>;
-    /** Accepted for parity; only `useForm` is used (no server upload by the widget). */
+    /** Text beside the button; the active language's "or Drop here" when unset. */
+    readonly labelText: _angular_core.InputSignal<string | undefined>;
+    /** The button's text; the active language's "Select File" when unset. */
+    readonly selectButtonText: _angular_core.InputSignal<string | undefined>;
+    /** Accepted for parity; only `useForm` is used (no server upload by the widget). It also
+     *  gates the cancel button, which dx omits in `useForm` mode. */
     readonly uploadMode: _angular_core.InputSignal<"instantly" | "useButtons" | "useForm">;
     readonly multiple: _angular_core.InputSignal<boolean>;
     readonly name: _angular_core.InputSignal<string>;
     /** Group for a nested nxe-validator (none used today → bare default group). */
-    readonly validationGroupInput: _angular_core.InputSignal<string>;
+    readonly validationGroupInput: _angular_core.InputSignal<string | undefined>;
     /** Re-emits the native `<input type=file>` change so `$event.target.files[0]` keeps working. */
     readonly change: _angular_core.OutputEmitterRef<Event>;
     private readonly fileInput;
-    readonly file: _angular_core.WritableSignal<File>;
+    /** The library's runtime-switchable messages. */
+    protected readonly messages: NxeMessageService;
+    readonly file: _angular_core.WritableSignal<File | null>;
     readonly dragOver: _angular_core.WritableSignal<boolean>;
     readonly focused: _angular_core.WritableSignal<boolean>;
-    readonly validationError: _angular_core.WritableSignal<string>;
+    readonly validationError: _angular_core.WritableSignal<string | null>;
     getValue(): unknown;
     validationGroup(): string | undefined;
     setValidationError(message: string | null): void;
@@ -44,4 +54,226 @@ declare class NxeFileUploaderComponent implements NxeValidationTarget {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeFileUploaderComponent, "nxe-file-uploader", never, { "allowCanceling": { "alias": "allowCanceling"; "required": false; "isSignal": true; }; "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "labelText": { "alias": "labelText"; "required": false; "isSignal": true; }; "selectButtonText": { "alias": "selectButtonText"; "required": false; "isSignal": true; }; "uploadMode": { "alias": "uploadMode"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "validationGroupInput": { "alias": "validationGroup"; "required": false; "isSignal": true; }; }, { "change": "change"; }, never, ["*"], true, never>;
 }
 
-export { NxeFileUploaderComponent };
+/** Where a file is in its life: chosen, on its way to the server, there, or failed. */
+type NxeFileStatus = 'pending' | 'uploading' | 'uploaded' | 'error';
+/**
+ * One entry of the value of `nxe-file-input`: the file chosen, and what became of it.
+ *
+ * Descriptors are immutable; every change produces a new array of new objects. `file` is there while
+ * the browser still holds the `File` (a descriptor the server handed back has `serverId` and `url`
+ * instead), so a form without an upload can read the files straight from the value.
+ */
+interface NxeFileDescriptor {
+    /** Stable for the life of the entry; what `track` and the remove/retry/cancel calls use. */
+    readonly id: string;
+    readonly name: string;
+    /** Bytes. */
+    readonly size: number;
+    /** MIME type as the browser reported it; may be empty. */
+    readonly type: string;
+    readonly status: NxeFileStatus;
+    /** 0 to 100. Live while `uploading`; the value in the form is refreshed at each status change. */
+    readonly progress: number;
+    /** Why the upload failed or was cancelled. */
+    readonly error?: string;
+    readonly file?: File;
+    /** The server's id for the stored file, once uploaded. */
+    readonly serverId?: string;
+    /** Where the stored file can be fetched, once uploaded. */
+    readonly url?: string;
+}
+/** What an `uploadFn` may emit besides an `HttpEvent`: progress, and optionally the stored file's id and url. */
+interface NxeUploadProgress {
+    /** 0 to 100. */
+    readonly progress: number;
+    readonly serverId?: string;
+    readonly url?: string;
+}
+/** An event of an upload: an Angular `HttpEvent` (with `reportProgress`), `{ progress }`, or a bare percentage. */
+type NxeUploadEvent = HttpEvent<unknown> | NxeUploadProgress | number;
+/** What `uploadFn` receives besides the file. */
+interface NxeUploadContext {
+    /** Aborted when the user cancels or removes the file; pass it to `fetch`, or ignore it and unsubscribe. */
+    readonly signal: AbortSignal;
+    readonly descriptor: NxeFileDescriptor;
+}
+/**
+ * Uploads one file. Emit progress as it happens and complete when the file is stored; an error is a failed
+ * upload. Unsubscribing is how a cancel reaches you, as it is for `HttpClient`.
+ */
+type NxeUploadFn = (file: File, context: NxeUploadContext) => Observable<NxeUploadEvent>;
+/** What the server's response body says about the stored file. */
+interface NxeUploadResult {
+    readonly serverId?: string;
+    readonly url?: string;
+}
+/** Why a file cannot be kept, in the order the rules are checked. */
+type NxeFileIssueKind = 'fileType' | 'fileSize' | 'maxFiles';
+/** Whether `file` matches an `accept` list: `.pdf`, `application/pdf`, `image/*`, comma separated. Empty or `*` accepts all. */
+declare function nxeFileAccepted(file: {
+    readonly name: string;
+    readonly type: string;
+}, accept: string): boolean;
+
+/** One row of the list, with everything the template shows already worked out. */
+interface FileRow {
+    readonly file: NxeFileDescriptor;
+    /** Why this file cannot be kept (wrong type, too big, over the count), or `null`. */
+    readonly issue: {
+        readonly kind: NxeFileIssueKind;
+        readonly message: string;
+    } | null;
+    readonly sizeText: string;
+    readonly statusText: string;
+    readonly failed: boolean;
+    readonly canRetry: boolean;
+}
+/**
+ * `nxe-file-input` is a file field for forms: the value is the list of files, `NxeFileDescriptor[]`, and it
+ * works with `formControlName`, `[formControl]`, `ngModel` and `nxe-form-field`.
+ *
+ * ```html
+ * <nxe-form-field label="Invoice and supporting documents">
+ *     <nxe-file-input
+ *         formControlName="attachments"
+ *         accept=".pdf,image/*"
+ *         [maxSize]="5 * 1024 * 1024"
+ *         [maxFiles]="3"
+ *         uploadUrl="/api/files/upload" />
+ * </nxe-form-field>
+ * ```
+ *
+ * **Value.** A file the user picks or drops becomes `{ id, name, size, type, status, progress, file }`. With no
+ * upload configured it stays `pending` and the form reads the `File` from the value (to put in a `FormData`
+ * itself). With one, it is uploaded as soon as it is added (`autoUpload`, default) and moves through
+ * `uploading` to `uploaded` with the server's `serverId` and `url`, or to `error`. A descriptor that came from the
+ * server (`writeValue` with `status: 'uploaded'`) shows as an existing attachment, a link when it has a `url`.
+ * The form is told at each status change; the progress bar between them is live without churning the form.
+ *
+ * **Validation.** The control is invalid, with these error keys (which `nxe-form-field` words in the active
+ * language), until the problem is removed:
+ *
+ * | key | when | error value |
+ * |---|---|---|
+ * | `fileType` | a file does not match `accept` | `{ accept, files }` |
+ * | `fileSize` | a file is over `maxSize` bytes | `{ maxSize, files }` |
+ * | `maxFiles` | more files than `maxFiles` (1 when not `multiple`) | `{ maxFiles, actual }` |
+ * | `uploading` | an upload is running, or a file is waiting for one | `{ count }` |
+ * | `uploadFailed` | an upload failed or was cancelled | `{ files }` |
+ *
+ * A file that breaks a rule is kept in the list, marked, so the user sees which one and can remove it; it is never
+ * uploaded. `required` needs a file in the list.
+ *
+ * **Uploading.** `uploadUrl` posts a `FormData` (field `uploadField`) with `HttpClient` and `reportProgress`, so the
+ * app needs `provideHttpClient()` (and its interceptors apply). `uploadFn` is the same job in your hands:
+ * `(file, { signal }) => Observable` of `HttpEvent`s, `{ progress, serverId?, url? }` or percentages, completing
+ * on success. Cancel and remove unsubscribe, and abort `signal`. `uploadResult` maps the response body to
+ * `{ serverId, url }` (default: `serverId` or `id`, and `url`).
+ */
+declare class NxeFileInputComponent extends NxeFormControlBase<NxeFileDescriptor[]> implements Validator {
+    /** Accepted files, as in `<input accept>`: `.pdf`, `application/pdf`, `image/*`, comma separated. Empty accepts all. */
+    readonly accept: _angular_core.InputSignal<string>;
+    /** Largest file, in bytes. */
+    readonly maxSize: _angular_core.InputSignalWithTransform<number | undefined, unknown>;
+    /** Most files the control may hold. */
+    readonly maxFiles: _angular_core.InputSignalWithTransform<number | undefined, unknown>;
+    /** More than one file. When off, choosing a file replaces the current one. */
+    readonly multiple: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Uploads a file; see {@link NxeUploadFn}. Wins over `uploadUrl`. */
+    readonly uploadFn: _angular_core.InputSignal<NxeUploadFn | undefined>;
+    /** Where to POST each file, with `HttpClient`. */
+    readonly uploadUrl: _angular_core.InputSignal<string | undefined>;
+    /** Name of the form field the file is sent as. */
+    readonly uploadField: _angular_core.InputSignal<string>;
+    /** Headers for the `uploadUrl` request. */
+    readonly uploadHeaders: _angular_core.InputSignal<Record<string, string | string[]> | undefined>;
+    /** Send cookies with the `uploadUrl` request. */
+    readonly withCredentials: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Reads `{ serverId, url }` from the response body. */
+    readonly uploadResult: _angular_core.InputSignal<((body: unknown) => NxeUploadResult) | undefined>;
+    /** Start uploading as soon as a file is added. Off, call {@link upload}. */
+    readonly autoUpload: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** The button's text; the active language's "Select files" when unset. */
+    readonly selectButtonText: _angular_core.InputSignal<string | undefined>;
+    /** Text beside the button; the active language's "or drop files here" when unset. */
+    readonly labelText: _angular_core.InputSignal<string | undefined>;
+    /** Show the accepted types, size and count under the button. */
+    readonly showHints: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Files were added, with their descriptors. */
+    readonly filesAdded: _angular_core.OutputEmitterRef<readonly NxeFileDescriptor[]>;
+    /** A file was removed (or replaced). Delete it from the server here, if it was stored. */
+    readonly fileRemoved: _angular_core.OutputEmitterRef<NxeFileDescriptor>;
+    /** An upload finished. */
+    readonly fileUploaded: _angular_core.OutputEmitterRef<NxeFileDescriptor>;
+    /** An upload failed or was cancelled. */
+    readonly fileFailed: _angular_core.OutputEmitterRef<NxeFileDescriptor>;
+    private readonly picker;
+    private readonly http;
+    private readonly injector;
+    private readonly destroyRef;
+    private readonly running;
+    private readonly results;
+    private validatorChange;
+    private announceToggle;
+    protected readonly dragOver: _angular_core.WritableSignal<boolean>;
+    protected readonly announcement: _angular_core.WritableSignal<string>;
+    /** The files in the control. */
+    readonly files: _angular_core.Signal<NxeFileDescriptor[]>;
+    /** An upload is configured. */
+    readonly uploads: _angular_core.Signal<boolean>;
+    /** Most files the control accepts: `maxFiles`, or one when not `multiple`. */
+    readonly limit: _angular_core.Signal<number>;
+    protected readonly canAdd: _angular_core.Signal<boolean>;
+    protected readonly rows: _angular_core.Signal<readonly FileRow[]>;
+    protected readonly hints: _angular_core.Signal<string[]>;
+    constructor();
+    validate(control: AbstractControl): ValidationErrors | null;
+    registerOnValidatorChange(fn: () => void): void;
+    /** Opens the browser's file picker. */
+    open(): void;
+    /** Adds files as if the user had chosen them. */
+    addFiles(list: readonly File[], event?: Event | null): void;
+    /** Removes a file, cancelling its upload if it is running. */
+    remove(id: string): void;
+    /** Stops a running upload. The file stays, as an error, so it can be retried or removed. */
+    cancel(id: string): void;
+    /** Uploads a failed or cancelled file again. */
+    retry(id: string): void;
+    /** Uploads every file that is waiting, for `autoUpload` off. */
+    upload(): void;
+    protected onPicked(event: Event): void;
+    protected onDragOver(event: DragEvent): void;
+    protected onDragLeave(event: DragEvent): void;
+    protected onDrop(event: DragEvent): void;
+    protected onZoneFocusOut(event: FocusEvent): void;
+    protected progressLabel(file: NxeFileDescriptor): string;
+    protected round(value: number): number;
+    protected t(key: NxeMessageKey, ...args: readonly unknown[]): string;
+    /** Why `file` at `index` cannot be kept; checked in the order type, size, count. */
+    private issueOf;
+    private statusText;
+    private describe;
+    private afterAdd;
+    /** Starts every pending file that breaks no rule, when uploads are on (`force` ignores `autoUpload`). */
+    private startEligible;
+    /** Marks `ids` as uploading in one change, then starts each request. */
+    private begin;
+    private request;
+    private onEvent;
+    private succeed;
+    private fail;
+    private messageOf;
+    private stopById;
+    private stop;
+    /** Applies changes to descriptors; `notify` tells the form, otherwise only the component's own value moves. */
+    private patch;
+    private say;
+    /** After a removal the focused button is gone: move to the neighbouring file, or to the picker button. */
+    private focusAfterRemove;
+    writeValue(value: NxeFileDescriptor[] | null): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeFileInputComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeFileInputComponent, "nxe-file-input", never, { "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "maxSize": { "alias": "maxSize"; "required": false; "isSignal": true; }; "maxFiles": { "alias": "maxFiles"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "uploadFn": { "alias": "uploadFn"; "required": false; "isSignal": true; }; "uploadUrl": { "alias": "uploadUrl"; "required": false; "isSignal": true; }; "uploadField": { "alias": "uploadField"; "required": false; "isSignal": true; }; "uploadHeaders": { "alias": "uploadHeaders"; "required": false; "isSignal": true; }; "withCredentials": { "alias": "withCredentials"; "required": false; "isSignal": true; }; "uploadResult": { "alias": "uploadResult"; "required": false; "isSignal": true; }; "autoUpload": { "alias": "autoUpload"; "required": false; "isSignal": true; }; "selectButtonText": { "alias": "selectButtonText"; "required": false; "isSignal": true; }; "labelText": { "alias": "labelText"; "required": false; "isSignal": true; }; "showHints": { "alias": "showHints"; "required": false; "isSignal": true; }; }, { "filesAdded": "filesAdded"; "fileRemoved": "fileRemoved"; "fileUploaded": "fileUploaded"; "fileFailed": "fileFailed"; }, never, never, true, never>;
+}
+
+export { NxeFileInputComponent, NxeFileUploaderComponent, nxeFileAccepted };
+export type { NxeFileDescriptor, NxeFileIssueKind, NxeFileStatus, NxeUploadContext, NxeUploadEvent, NxeUploadFn, NxeUploadProgress, NxeUploadResult };