feat(file-upload): duplicate handling and file select strategy (#DS-4617) (#1898)

Author: NikGurev

packages/components/file-upload/file-upload.en.md

@@ -65,3 +65,11 @@ The user can drag files onto the page, and at that moment a full-screen upload o
 ### Upload area
 
 The drag-and-drop area can be not only the entire screen or the File Upload component itself within a form, but also a separate part of the screen.
+
+### Adding files
+
+By default, every new selection is added to the files you already have — this makes it easy to build up a list over several picks.
+
+If you want a new selection to replace the previous one instead — the way a regular system file dialog works — use `addStrategy="replace"`.
+
+<!-- example(file-upload-multiple-add-strategy) -->

packages/components/file-upload/file-upload.ru.md

@@ -67,3 +67,11 @@
 Областью для перетаскивания может быть не только весь экран, сам компонент File Upload в форме, но и отдельная часть экрана
 
 <!-- example(file-upload-local-dropzone) -->
+
+### Добавление файлов
+
+По умолчанию каждый новый выбор файлов добавляется к уже загруженным — так удобно собирать список за несколько заходов.
+
+Если нужно, чтобы новый выбор заменял предыдущий — как в обычном системном диалоге выбора файлов, — используйте `addStrategy="replace"`.
+
+<!-- example(file-upload-multiple-add-strategy) -->

packages/components/file-upload/file-upload.spec.ts

@@ -27,7 +27,7 @@ import {
 import { Observable, timer } from 'rxjs';
 import { map } from 'rxjs/operators';
 import { KbqDropzoneData, KbqFullScreenDropzoneService, KbqLocalDropzone } from './dropzone';
-import { KbqFileItem } from './file-upload';
+import { KbqFileItem, KbqFileUploadAddStrategy, KbqFileUploadAddStrategyValues } from './file-upload';
 import { KbqFileUploadModule } from './file-upload.module';
 import { KbqInputFileMultipleLabel, KbqMultipleFileUploadComponent } from './multiple-file-upload.component';
 import { KbqFileDropDirective } from './primitives/file-drop';
@@ -329,6 +329,69 @@ describe(KbqMultipleFileUploadComponent.name, () => {
         });
     });
 
+    describe('with addStrategy input', () => {
+        // Same object reused across dispatches so name/size/type/lastModified are guaranteed
+        // identical, instead of relying on two `new File(...)` calls landing in the same millisecond.
+        const duplicateFile: Partial<File> = { name: FILE_NAME, size: 4, type: '', lastModified: 1700000000000 };
+        const otherFile: Partial<File> = { name: 'other.file', size: 4, type: '', lastModified: 1700000000000 };
+
+        // The native input is inside the `@if (!files.length) {...} @else {...}` branch of the
+        // template, so it gets destroyed/recreated when the file count crosses zero — must be
+        // re-queried before every dispatch rather than cached once.
+        const dispatchChange = (file: Partial<File>) => {
+            dispatchEvent(component.fileUpload().input!.nativeElement, getMockedChangeEvent(file));
+            fixture.detectChanges();
+        };
+
+        it('should default to concat strategy', () => {
+            expect(component.fileUpload().addStrategy()).toBe(KbqFileUploadAddStrategy.Concat);
+        });
+
+        describe('concat strategy (default)', () => {
+            it('should skip a file that duplicates one already in the list', () => {
+                dispatchChange(duplicateFile);
+                dispatchChange(duplicateFile);
+
+                expect(component.files).toHaveLength(1);
+            });
+
+            it('should still add files that are genuinely different', () => {
+                dispatchChange(duplicateFile);
+                dispatchChange(otherFile);
+
+                expect(component.files).toHaveLength(2);
+            });
+
+            it('should emit filesAdded with an empty array for a skipped duplicate', () => {
+                const filesAddedSpy = jest.fn();
+                const subscription = component.fileUpload().filesAdded.subscribe(filesAddedSpy);
+
+                dispatchChange(duplicateFile);
+                dispatchChange(duplicateFile);
+
+                subscription.unsubscribe();
+
+                expect(filesAddedSpy).toHaveBeenCalledTimes(2);
+                expect(filesAddedSpy.mock.calls[1][0]).toHaveLength(0);
+            });
+        });
+
+        describe('replace strategy', () => {
+            beforeEach(() => {
+                component.addStrategy.set(KbqFileUploadAddStrategy.Replace);
+                fixture.detectChanges();
+            });
+
+            it('should replace the list instead of appending on a new selection', () => {
+                dispatchChange(duplicateFile);
+                dispatchChange(otherFile);
+
+                expect(component.files).toHaveLength(1);
+                expect(component.files[0].file.name).toBe('other.file');
+            });
+        });
+    });
+
     describe('with ControlValueAccessor', () => {
         let fixture: ComponentFixture<ControlValueAccessorMultipleFileUpload>;
         let component: ControlValueAccessorMultipleFileUpload;
@@ -1764,6 +1827,7 @@ class ControlValueAccessorSingleFileUpload {
                 [disabled]="disabled"
                 [fullScreenDropZone]="fullScreenDropZone()"
                 [localeConfig]="localeConfig()"
+                [addStrategy]="addStrategy()"
                 (fileQueueChanged)="onChange($event)"
             />
         </div>
@@ -1777,6 +1841,7 @@ class BasicMultipleFileUpload {
     disabled: boolean;
     files: KbqFileItem[];
     fullScreenDropZone = signal<KbqDropzoneData | boolean | undefined>(undefined);
+    addStrategy = signal<KbqFileUploadAddStrategyValues>(KbqFileUploadAddStrategy.Concat);
 
     localeConfig = signal<Partial<KbqBaseFileUploadLocaleConfig>>({});
 

packages/components/file-upload/file-upload.ts

@@ -42,6 +42,17 @@ export enum KbqFileUploadAllowedType {
 /** Allowed upload modes for the upload component. */
 export type KbqFileUploadAllowedTypeValues = KbqEnumValues<KbqFileUploadAllowedType>;
 
+/** Strategy for merging newly selected/dropped files into the existing file list. */
+export enum KbqFileUploadAddStrategy {
+    /** Accumulates files across interactions, skipping files that duplicate ones already present. */
+    Concat = 'concat',
+    /** Discards the previous selection, mirroring native `<input multiple>` behavior. */
+    Replace = 'replace'
+}
+
+/** Allowed add strategies for the upload component. */
+export type KbqFileUploadAddStrategyValues = KbqEnumValues<KbqFileUploadAddStrategy>;
+
 /** @docs-private */
 export type KbqFileUploadCaptionContext = {
     captionText: string;

packages/components/file-upload/multiple-file-upload.component.ts

@@ -41,6 +41,8 @@ import {
     KBQ_FILE_UPLOAD_CONFIGURATION,
     KbqFile,
     KbqFileItem,
+    KbqFileUploadAddStrategy,
+    KbqFileUploadAddStrategyValues,
     KbqFileUploadAllowedType,
     KbqFileUploadBase,
     KbqFileUploadCaptionContext
@@ -132,6 +134,13 @@ export class KbqMultipleFileUploadComponent
      * Provide configuration object to enable, or undefined to disable.
      */
     fullScreenDropZone = input<KbqDropzoneData | boolean>();
+    /**
+     * Controls how newly selected/dropped files are merged into the existing list.
+     * `concat` accumulates files across interactions, skipping files that duplicate ones already present.
+     * `replace` discards the previous selection, mirroring native input file multiple behavior.
+     * @default concat
+     */
+    readonly addStrategy = input<KbqFileUploadAddStrategyValues>(KbqFileUploadAddStrategy.Concat);
 
     /** Optional configuration to override default labels with localized text.*/
     readonly localeConfig = input<Partial<KbqMultipleFileUploadLocaleConfig>>();
@@ -391,7 +400,12 @@ export class KbqMultipleFileUploadComponent
     }
 
     private onFileAdded(filesToAdd: KbqFileItem[]) {
-        this.fileList.addArray(filesToAdd);
+        if (this.addStrategy() === KbqFileUploadAddStrategy.Replace) {
+            this.fileList.replace(filesToAdd);
+        } else {
+            filesToAdd = filesToAdd.filter((fileToAdd) => !this.isDuplicate(fileToAdd.file, this.files));
+            this.fileList.addArray(filesToAdd);
+        }
 
         this.cvaOnChange(this.files);
 
@@ -400,4 +414,14 @@ export class KbqMultipleFileUploadComponent
         this.fileQueueChanged.emit(this.files);
         this.onTouched();
     }
+
+    private isDuplicate(candidate: File, existing: KbqFileItem[]): boolean {
+        return existing.some(
+            ({ file }) =>
+                file.name === candidate.name &&
+                file.size === candidate.size &&
+                file.lastModified === candidate.lastModified &&
+                file.type === candidate.type
+        );
+    }
 }

packages/components/file-upload/primitives/file-picker.spec.ts

@@ -437,6 +437,21 @@ describe('KbqFileList', () => {
         });
     });
 
+    describe('replace', () => {
+        it('should replace the list with the specified items and emit event', () => {
+            directive.addArray([file1, file3]);
+            directive.replace([file1, file2, file3]);
+            expect(directive.list()).toEqual([file1, file2, file3]);
+            expect(component.itemsAddedEvent).toEqual([file1, file2, file3]);
+        });
+
+        it('should emit itemsAdded event with added items', () => {
+            directive.replace([file1, file2]);
+            fixture.detectChanges();
+            expect(component.itemsAddedEvent).toEqual([file1, file2]);
+        });
+    });
+
     describe('remove', () => {
         beforeEach(() => {
             directive.list.set([]);

packages/components/file-upload/primitives/file-picker.ts

@@ -131,6 +131,12 @@ export class KbqFileList<T> {
         this.itemsAdded.emit(items);
     }
 
+    /** Replaces the current list with the specified items and emits event. */
+    replace(items: T[]): void {
+        this.update(() => items);
+        this.itemsAdded.emit(items);
+    }
+
     /** Removes the first occurrence of the specified item. Returns removed items and emits event. */
     remove(item: T): T[] {
         const removed: T[] = [];

packages/docs-examples/components/file-upload/file-upload-multiple-add-strategy/file-upload-multiple-add-strategy-example.ts

@@ -0,0 +1,23 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
+import { KbqIconModule } from '@koobiq/components/icon';
+
+/**
+ * @title File-upload multiple add strategy
+ */
+@Component({
+    selector: 'file-upload-multiple-add-strategy-example',
+    imports: [
+        KbqIconModule,
+        KbqMultipleFileUploadComponent
+    ],
+    template: `
+        <kbq-multiple-file-upload [addStrategy]="'replace'">
+            <ng-template #kbqFileIcon>
+                <i kbq-icon="kbq-file-text-o_16"></i>
+            </ng-template>
+        </kbq-multiple-file-upload>
+    `,
+    changeDetection: ChangeDetectionStrategy.OnPush
+})
+export class FileUploadMultipleAddStrategyExample {}

packages/docs-examples/components/file-upload/index.ts

@@ -6,6 +6,7 @@ import { FileUploadDropzoneExample } from './file-upload-dropzone/file-upload-dr
 import { FileUploadIndeterminateLoadingOverviewExample } from './file-upload-indeterminate-loading-overview/file-upload-indeterminate-loading-overview-example';
 import { FileUploadLocalDropzoneExample } from './file-upload-local-dropzone/file-upload-local-dropzone-example';
 import { FileUploadMultipleAcceptValidationExample } from './file-upload-multiple-accept-validation/file-upload-multiple-accept-validation-example';
+import { FileUploadMultipleAddStrategyExample } from './file-upload-multiple-add-strategy/file-upload-multiple-add-strategy-example';
 import { FileUploadMultipleCompactOverviewExample } from './file-upload-multiple-compact-overview/file-upload-multiple-compact-overview-example';
 import { FileUploadMultipleCustomTextOverviewExample } from './file-upload-multiple-custom-text-overview/file-upload-multiple-custom-text-overview-example';
 import { FileUploadMultipleDefaultOverviewExample } from './file-upload-multiple-default-overview/file-upload-multiple-default-overview-example';
@@ -36,6 +37,7 @@ export {
     FileUploadIndeterminateLoadingOverviewExample,
     FileUploadLocalDropzoneExample,
     FileUploadMultipleAcceptValidationExample,
+    FileUploadMultipleAddStrategyExample,
     FileUploadMultipleCompactOverviewExample,
     FileUploadMultipleCustomTextOverviewExample,
     FileUploadMultipleDefaultOverviewExample,
@@ -74,6 +76,7 @@ const EXAMPLES = [
     FileUploadMultipleDefaultValidationReactiveFormsOverviewExample,
     FileUploadMultipleDefaultOverviewExample,
     FileUploadMultipleCustomTextOverviewExample,
+    FileUploadMultipleAddStrategyExample,
     FileUploadIndeterminateLoadingOverviewExample,
     FileUploadMultipleCompactOverviewExample,
     FileUploadSingleRequiredReactiveValidationExample,

tools/public_api_guard/components/file-upload.api.md

@@ -151,6 +151,7 @@ export class KbqFileList<T> {
     readonly list: _angular_core.ModelSignal<T[]>;
     remove(item: T): T[];
     removeAt(index: number): T[];
+    replace(items: T[]): void;
     // (undocumented)
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<KbqFileList<any>, "[kbqFileList]", ["kbqFileList"], { "list": { "alias": "list"; "required": false; "isSignal": true; }; }, { "list": "listChange"; "itemRemoved": "itemRemoved"; "itemsAdded": "itemsAdded"; }, never, never, true, never>;
     // (undocumented)
@@ -177,6 +178,15 @@ export class KbqFileLoader {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqFileLoader, never>;
 }
 
+// @public
+export enum KbqFileUploadAddStrategy {
+    Concat = "concat",
+    Replace = "replace"
+}
+
+// @public
+export type KbqFileUploadAddStrategyValues = KbqEnumValues<KbqFileUploadAddStrategy>;
+
 // @public
 export enum KbqFileUploadAllowedType {
     // (undocumented)
@@ -300,6 +310,7 @@ export class KbqMultipleFileUploadComponent extends KbqFileUploadBase implements
     constructor();
     readonly accept: _angular_core.InputSignal<string[] | undefined>;
     get acceptedFiles(): string;
+    readonly addStrategy: _angular_core.InputSignal<"concat" | "replace">;
     allowed: _angular_core.InputSignal<"file" | "folder" | "mixed">;
     protected readonly captionContext: _angular_core.Signal<KbqFileUploadCaptionContext>;
     protected get captionTextWhenSelected(): string;
@@ -347,7 +358,7 @@ export class KbqMultipleFileUploadComponent extends KbqFileUploadBase implements
     readonly size: _angular_core.InputSignal<"compact" | "default">;
     writeValue(files: FileList | KbqFileItem[] | null): void;
     // (undocumented)
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<KbqMultipleFileUploadComponent, "kbq-multiple-file-upload,kbq-file-upload[multiple]", never, { "progressMode": { "alias": "progressMode"; "required": false; "isSignal": true; }; "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "inputId": { "alias": "inputId"; "required": false; "isSignal": true; }; "errorStateMatcher": { "alias": "errorStateMatcher"; "required": false; }; "files": { "alias": "files"; "required": false; }; "allowed": { "alias": "allowed"; "required": false; "isSignal": true; }; "fullScreenDropZone": { "alias": "fullScreenDropZone"; "required": false; "isSignal": true; }; "localeConfig": { "alias": "localeConfig"; "required": false; "isSignal": true; }; }, { "filesChange": "filesChange"; "fileQueueChanged": "fileQueueChanged"; "filesAdded": "filesAdded"; "fileRemoved": "fileRemoved"; }, ["customFileIcon", "hint"], ["kbq-hint"], true, [{ directive: typeof KbqFileUploadContext; inputs: { "id": "id"; "disabled": "disabled"; }; outputs: {}; }, { directive: typeof KbqFileList; inputs: {}; outputs: { "itemsAdded": "itemsAdded"; "itemRemoved": "itemRemoved"; }; }]>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<KbqMultipleFileUploadComponent, "kbq-multiple-file-upload,kbq-file-upload[multiple]", never, { "progressMode": { "alias": "progressMode"; "required": false; "isSignal": true; }; "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "inputId": { "alias": "inputId"; "required": false; "isSignal": true; }; "errorStateMatcher": { "alias": "errorStateMatcher"; "required": false; }; "files": { "alias": "files"; "required": false; }; "allowed": { "alias": "allowed"; "required": false; "isSignal": true; }; "fullScreenDropZone": { "alias": "fullScreenDropZone"; "required": false; "isSignal": true; }; "addStrategy": { "alias": "addStrategy"; "required": false; "isSignal": true; }; "localeConfig": { "alias": "localeConfig"; "required": false; "isSignal": true; }; }, { "filesChange": "filesChange"; "fileQueueChanged": "fileQueueChanged"; "filesAdded": "filesAdded"; "fileRemoved": "fileRemoved"; }, ["customFileIcon", "hint"], ["kbq-hint"], true, [{ directive: typeof KbqFileUploadContext; inputs: { "id": "id"; "disabled": "disabled"; }; outputs: {}; }, { directive: typeof KbqFileList; inputs: {}; outputs: { "itemsAdded": "itemsAdded"; "itemRemoved": "itemRemoved"; }; }]>;
     // (undocumented)
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqMultipleFileUploadComponent, never>;
 }