ng-hub-ui-forms 22.4.0 → 22.6.0

package/types/ng-hub-ui-forms.d.ts

@@ -1,7 +1,7 @@
 import * as _angular_core from '@angular/core';
-import { OnInit, AfterContentInit, OnDestroy, TemplateRef, ElementRef, InjectionToken, EnvironmentProviders, PipeTransform, NgZone, ViewContainerRef } from '@angular/core';
+import { OnInit, AfterContentInit, OnDestroy, TemplateRef, ElementRef, InjectionToken, EnvironmentProviders, Type, PipeTransform, NgZone, ViewContainerRef } from '@angular/core';
 import { NgControl, ControlContainer, ControlValueAccessor, ValidationErrors, AbstractControl, ValidatorFn } from '@angular/forms';
-import { Subject, OperatorFunction } from 'rxjs';
+import { Subject, Observable, OperatorFunction } from 'rxjs';
 import * as ng_hub_ui_forms from 'ng-hub-ui-forms';
 import { SafeUrl } from '@angular/platform-browser';
 
@@ -283,6 +283,85 @@ declare const defaultHubDatepickerLabels: HubDatepickerLabels;
 /** Built-in datepicker defaults. */
 declare const defaultHubDatepickerConfig: HubDatepickerConfig;
 
+/** Why a file was refused by `<hub-file-input>` before it ever reached the form value. */
+type HubFileRejectionReason = 'accept' | 'maxSize' | 'minSize' | 'maxFiles' | 'maxTotalSize' | 'duplicate';
+/** A file the component refused, together with the constraint that refused it. */
+interface HubFileRejection {
+    /** The refused file. */
+    file: File;
+    /** The constraint that refused it. */
+    reason: HubFileRejectionReason;
+    /** The configured limit that was violated (`accept` string, byte count, file count), when applicable. */
+    limit: string | number | null;
+}
+/** Lifecycle of a single accepted file. `uploading`/`done`/`error` only occur when an uploader is registered. */
+type HubFileStatus = 'ready' | 'uploading' | 'done' | 'error';
+/**
+ * The rich, per-file state exposed by `<hub-file-input>` through its `files()` signal.
+ *
+ * This is deliberately **not** the form-control value: the control holds plain `File` objects so it
+ * can be handed straight to a `FormData`. Preview URLs, upload status and progress live here.
+ */
+interface HubFileItem {
+    /** Stable id for the lifetime of the item; used by `remove`, `cancel` and `retry`. */
+    readonly id: string;
+    /** The underlying native file. */
+    readonly file: File;
+    /** Object URL of the thumbnail, for image files in a browser. `null` otherwise. */
+    readonly previewUrl: string | null;
+    /** Current lifecycle status. */
+    readonly status: HubFileStatus;
+    /**
+     * Upload progress from 0 to 100, or `null` when the total size is unknown — the case when the
+     * transport does not report a total (e.g. `HttpClient` emits `total: undefined`). A `null`
+     * progress must render as an indeterminate bar, never as 0%.
+     */
+    readonly progress: number | null;
+    /** The error thrown by the uploader, when `status` is `'error'`. */
+    readonly error: unknown | null;
+}
+/** How the accepted files are previewed below the dropzone. */
+type HubFilePreview = 'none' | 'list' | 'grid';
+/** The active restrictions of a `<hub-file-input>`, handed to the `constraints` label. */
+interface HubFileConstraints {
+    /** The `accept` specification, or `null` when everything is allowed. */
+    accept: string | null;
+    /** Maximum size per file in bytes, or `null`. */
+    maxSize: number | null;
+    /** Maximum number of files, or `null`. */
+    maxFiles: number | null;
+}
+/**
+ * Localizable, overridable labels for `<hub-file-input>`.
+ *
+ * Set them globally through {@link provideHubForms}; they cover both visible text and the
+ * accessible names of the internal buttons.
+ */
+interface HubFileInputLabels {
+    /** Text of the button that opens the native file dialog. */
+    browse: string;
+    /** Invitation rendered inside the dropzone. */
+    dropHere: string;
+    /** Accessible name of the per-file remove button. */
+    remove: string;
+    /** Text + accessible name of the "remove all" button. */
+    clear: string;
+    /** Accessible name of the per-file retry button (uploader only). */
+    retry: string;
+    /** Accessible name of the per-file cancel button (uploader only). */
+    cancel: string;
+    /** Screen-reader summary of the current selection. */
+    filesSelected: (count: number) => string;
+    /** Renders a byte count as human-readable text. */
+    formatSize: (bytes: number) => string;
+    /** Renders the reason a file was refused; announced in the live region. */
+    rejection: (rejection: HubFileRejection) => string;
+    /** Renders the hint that summarizes the active restrictions under the dropzone. */
+    constraints: (constraints: HubFileConstraints) => string;
+}
+/** Built-in (English) file-input labels. */
+declare const defaultHubFileInputLabels: HubFileInputLabels;
+
 /**
  * Global configuration contract for `ng-hub-ui-forms`.
  */
@@ -303,6 +382,8 @@ interface HubFormsConfig {
     showValid: boolean;
     /** Global datepicker defaults (locale labels, formats, first day of week…). */
     datepicker: HubDatepickerConfig;
+    /** Global file-input labels (button text, accessible names, size and rejection formatting). */
+    fileInput: HubFileInputLabels;
 }
 /**
  * Default configuration used when {@link provideHubForms} is not called.
@@ -338,6 +419,105 @@ type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
 };
 
+/**
+ * An event emitted while a single file is being uploaded.
+ *
+ * `progress` carries the raw `loaded`/`total` byte counts rather than a percentage, so a transport
+ * that does not know the total (`HttpClient` emits `total: undefined` when the request body is
+ * streamed) can say so with `total: null` instead of pretending the upload sits at 0%.
+ */
+type HubFileUploadEvent = {
+    status: 'progress';
+    loaded: number;
+    total: number | null;
+} | {
+    status: 'done';
+    response?: unknown;
+} | {
+    status: 'error';
+    error: unknown;
+};
+/**
+ * Contract every uploader must satisfy to plug into `<hub-file-input>`.
+ *
+ * The library ships the **mechanism**, never a transport: endpoints, field names, headers and retry
+ * policies belong to the application. Register an implementation with {@link provideHubFileUploader}.
+ *
+ * The returned observable **must be cold**: one subscription equals one request. `<hub-file-input>`
+ * cancels an upload by unsubscribing (which aborts the underlying `XMLHttpRequest` when the
+ * implementation is built on `HttpClient`) and retries it by re-subscribing. An uploader that
+ * returns a hot or shared observable silently breaks cancellation.
+ *
+ * @example
+ * ```ts
+ * @Injectable({ providedIn: 'root' })
+ * export class ApiFileUploader implements HubFileUploader {
+ *   readonly #http = inject(HttpClient);
+ *
+ *   upload(file: File): Observable<HubFileUploadEvent> {
+ *     const body = new FormData();
+ *     body.append('file', file);
+ *
+ *     return this.#http.post('/api/files', body, { reportProgress: true, observe: 'events' }).pipe(
+ *       map((event) => {
+ *         if (event.type === HttpEventType.UploadProgress) {
+ *           return { status: 'progress', loaded: event.loaded, total: event.total ?? null } as const;
+ *         }
+ *         if (event.type === HttpEventType.Response) {
+ *           return { status: 'done', response: event.body } as const;
+ *         }
+ *         return null;
+ *       }),
+ *       filter((event) => event !== null),
+ *       catchError((error) => of({ status: 'error', error } as const))
+ *     );
+ *   }
+ * }
+ * ```
+ */
+interface HubFileUploader {
+    /**
+     * Uploads a single file.
+     *
+     * @param file - The file to upload.
+     * @param context - The id of the {@link HubFileItem} the file belongs to, for correlation.
+     * @returns A cold observable emitting progress, then either `done` or `error`.
+     */
+    upload(file: File, context: {
+        id: string;
+    }): Observable<HubFileUploadEvent>;
+}
+
+/**
+ * Injection token holding the {@link HubFileUploader} that `<hub-file-input>` delegates uploads to.
+ *
+ * It has **no default**: when nothing is registered, the component resolves it as `null` and behaves
+ * as a pure picker — no automatic upload, no progress bar, no cancel or retry. Register one with
+ * {@link provideHubFileUploader}.
+ */
+declare const HUB_FILE_UPLOADER: InjectionToken<HubFileUploader>;
+/**
+ * Registers the uploader that `<hub-file-input>` uses to send files.
+ *
+ * The library defines the contract, not the transport: an uploader that knows your endpoint, field
+ * name, headers and retry policy is application code. Implement {@link HubFileUploader} there and
+ * hand it over here.
+ *
+ * Passing a class provides it in the same injector and aliases the token to that single instance, so
+ * the uploader can inject `HttpClient` and hold its own state.
+ *
+ * @param uploader - The uploader class (dependency-injected) or a ready-made instance.
+ * @returns Environment providers to add to `bootstrapApplication` (or a route's `providers`).
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(App, {
+ *   providers: [provideHttpClient(), provideHubFileUploader(ApiFileUploader)]
+ * });
+ * ```
+ */
+declare function provideHubFileUploader(uploader: HubFileUploader | Type<HubFileUploader>): EnvironmentProviders;
+
 /**
  * Possible display types for form helper text.
  */
@@ -432,9 +612,13 @@ type HubInputValue = number | string | boolean | File | FileList | null;
  * `invalidFeedbackTemplateFn` input, or projected `hubValidationError` templates.
  *
  * Formats: `text`, `number`, `password`, `email`, `tel`, `url`, `color`, `checkbox`, `switch`,
- * `counter`. Label types: `stacked`, `floating`, `horizontal`. Text-like formats support prepend /
- * append addons (input groups). Numeric formats auto-attach `min`/`max` validators when bound to a
- * reactive control.
+ * `counter` and `file`. Label types: `stacked`, `floating`, `horizontal`. Text-like formats support
+ * prepend / append addons (input groups). Numeric formats auto-attach `min`/`max` validators when
+ * bound to a reactive control.
+ *
+ * The `file` format is **deprecated since 22.6.0** in favour of `<hub-file-input>`: it is a bare
+ * picker that cannot enforce `accept` on a drop, and has no size limits, no preview and no per-file
+ * removal. It keeps working until the next major.
  *
  * @example
  * ```html
@@ -520,11 +704,24 @@ declare class HubInputComponent extends HubFieldControl {
     readonly search: _angular_core.OutputEmitterRef<string>;
     /** Clears any pending debounce timer when the component is destroyed. */
     private readonly _searchCleanup;
-    /** Accepted file types (file format), e.g. `image/*,.pdf`. */
+    /**
+     * Accepted file types (file format), e.g. `image/*,.pdf`.
+     *
+     * @deprecated Since 22.6.0. Use `<hub-file-input>`, which enforces `accept` on drops and pastes
+     * too. Removed in the next major.
+     */
     readonly accept: _angular_core.InputSignal<string>;
-    /** Whether multiple files can be selected (file format). */
+    /**
+     * Whether multiple files can be selected (file format).
+     *
+     * @deprecated Since 22.6.0. Use `<hub-file-input>`. Removed in the next major.
+     */
     readonly multiple: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /** Text of the file-picker button (file format). */
+    /**
+     * Text of the file-picker button (file format).
+     *
+     * @deprecated Since 22.6.0. Use `<hub-file-input>` and its `buttonLabel`. Removed in the next major.
+     */
     readonly buttonLabel: _angular_core.InputSignal<string>;
     /** Reference to the hidden native file input. */
     protected readonly fileInput: _angular_core.Signal<ElementRef<HTMLInputElement> | undefined>;
@@ -813,14 +1010,20 @@ declare class HubSegmentedComponent extends HubFieldControl {
     /** Visual density. */
     readonly size: _angular_core.InputSignal<HubSegmentedSize>;
     /**
-     * Semantic accent for the selected pill. Drives `data-variant` on the bar, which re-bases the
-     * `--hub-segmented-selected-*` tokens. Built-in values map to the design-system palette
-     * (`primary`, `secondary`, `success`, `danger`, `warning`, `info`, `neutral`), but the set is
-     * OPEN — any custom string works as long as the consumer supplies the matching
-     * `--hub-segmented-selected-bg` / `--hub-segmented-selected-color` (or `--hub-segmented-accent`)
-     * for that `data-variant`. Empty string (default) keeps the neutral white-pill look.
+     * Accent for the selected pill. Accepts ANY colour value:
+     * - a built-in semantic name (`primary`, `success`, …) or any registered accent → resolves to
+     *   the matching `--hub-sys-color-*` design-system token;
+     * - a literal colour (`#ff0000`, `rgb(...)`, `oklch(...)`, `rebeccapurple`) → used as-is.
+     * Both the sliding indicator and the multiple-mode pill follow it, and the selected label gets a
+     * derived contrast colour automatically. Empty string (default) keeps the neutral white-pill look.
      */
     readonly color: _angular_core.InputSignal<string>;
+    /**
+     * Resolves {@link color} to a paintable accent for the `--hub-segmented-accent` slot: a bareword
+     * becomes a `--hub-sys-color-*` token with the word as raw fallback (so named CSS colours work
+     * too), while a literal `#hex` / `rgb()` / `oklch()` / `var()` is passed through unchanged.
+     */
+    protected readonly accentVar: _angular_core.Signal<string | null>;
     /** Label text. */
     readonly label: _angular_core.InputSignal<string>;
     /** Label display type (`stacked`, `horizontal`). */
@@ -1272,6 +1475,304 @@ declare class HubDatepickerComponent extends HubFieldControl {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubDatepickerComponent, "hub-datepicker", never, { "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "labelType": { "alias": "labelType"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "locale": { "alias": "locale"; "required": false; "isSignal": true; }; "firstDayOfWeek": { "alias": "firstDayOfWeek"; "required": false; "isSignal": true; }; "weekdayFormat": { "alias": "weekdayFormat"; "required": false; "isSignal": true; }; "displayFormat": { "alias": "displayFormat"; "required": false; "isSignal": true; }; "rangeSeparator": { "alias": "rangeSeparator"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "disabledDates": { "alias": "disabledDates"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "showToday": { "alias": "showToday"; "required": false; "isSignal": true; }; "closeOnSelect": { "alias": "closeOnSelect"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "formText": { "alias": "formText"; "required": false; "isSignal": true; }; "formTextType": { "alias": "formTextType"; "required": false; "isSignal": true; }; "classlist": { "alias": "classlist"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; "opened": "opened"; "closed": "closed"; "viewChange": "viewChange"; "cleared": "cleared"; }, never, never, true, never>;
 }
 
+/** Context handed to a projected `hubFileIcon` template. */
+interface HubFileIconContext {
+    /** The item whose icon is being rendered. */
+    $implicit: HubFileItem;
+}
+/**
+ * Overrides the glyph `<hub-file-input>` renders next to a non-image file.
+ *
+ * The library never depends on `ng-hub-ui-icons`: it draws a neutral document glyph from the
+ * `--hub-file-input-file-icon` CSS token and lets you project anything richer — a `<hub-icon>` from
+ * any pack, an inline `<svg>`, an emoji — through this template. The item is the implicit context,
+ * so the glyph can vary with `file.type`.
+ *
+ * @example
+ * ```html
+ * <hub-file-input formControlName="attachments" [multiple]="true">
+ *   <ng-template hubFileIcon let-item>
+ *     <hub-icon [name]="item.file.type === 'application/pdf' ? 'fa:solid:file-pdf' : 'fa:solid:file'" />
+ *   </ng-template>
+ * </hub-file-input>
+ * ```
+ */
+declare class HubFileIconDirective {
+    /** Template reference for the icon. */
+    readonly template: TemplateRef<HubFileIconContext>;
+    /**
+     * Narrows the implicit context for the template type-checker.
+     *
+     * @param _directive - The directive instance.
+     * @param _context - The candidate context.
+     * @returns Always `true`; exists only to type `let-item`.
+     */
+    static ngTemplateContextGuard(_directive: HubFileIconDirective, _context: unknown): _context is HubFileIconContext;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubFileIconDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<HubFileIconDirective, "[hubFileIcon]", never, {}, {}, never, never, true, never>;
+}
+
+/** Context handed to a projected `hubFilePreview` template. */
+interface HubFilePreviewContext {
+    /** The item being rendered. */
+    $implicit: HubFileItem;
+    /** Removes this item from the selection (and cancels its upload, if any). */
+    remove: () => void;
+    /** Re-runs the upload of this item. No-op when no uploader is registered. */
+    retry: () => void;
+    /** Aborts the in-flight upload of this item. No-op when it is not uploading. */
+    cancel: () => void;
+}
+/**
+ * Replaces the entire rendering of a selected file in `<hub-file-input>`.
+ *
+ * Where `hubFileIcon` swaps a glyph, this takes over the whole row (or grid tile): thumbnail, name,
+ * size, progress bar and buttons. The template receives the item plus the actions it needs, so a
+ * custom preview keeps working removal, retry and cancel without reaching into the component.
+ *
+ * @example
+ * ```html
+ * <hub-file-input formControlName="attachments" [multiple]="true">
+ *   <ng-template hubFilePreview let-item let-remove="remove">
+ *     <article class="attachment">
+ *       <img *ngIf="item.previewUrl" [src]="item.previewUrl" alt="" />
+ *       <span>{{ item.file.name }}</span>
+ *       <button type="button" (click)="remove()">Remove</button>
+ *     </article>
+ *   </ng-template>
+ * </hub-file-input>
+ * ```
+ */
+declare class HubFilePreviewDirective {
+    /** Template reference for the item. */
+    readonly template: TemplateRef<HubFilePreviewContext>;
+    /**
+     * Narrows the context for the template type-checker.
+     *
+     * @param _directive - The directive instance.
+     * @param _context - The candidate context.
+     * @returns Always `true`; exists only to type `let-item` and the action bindings.
+     */
+    static ngTemplateContextGuard(_directive: HubFilePreviewDirective, _context: unknown): _context is HubFilePreviewContext;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubFilePreviewDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<HubFilePreviewDirective, "[hubFilePreview]", never, {}, {}, never, never, true, never>;
+}
+
+/** The value a `<hub-file-input>` writes to its form control. */
+type HubFileValue = File | File[] | null;
+/**
+ * Normalizes any file-shaped control value to a plain array.
+ *
+ * Accepts the shapes a control can realistically hold: a single `File` (single mode), an array of
+ * files (multiple mode), a native `FileList` (a control fed straight from a DOM event or from the
+ * deprecated `<hub-input type="file">`), or `null`/`undefined`.
+ *
+ * @param value - The raw control value.
+ * @returns The files it contains, in order; an empty array when it holds none.
+ */
+declare function toFileArray(value: unknown): File[];
+
+/**
+ * Accessible file field with drag-and-drop, clipboard paste, per-file constraints, previews and
+ * optional upload progress.
+ *
+ * A full `ng-hub-ui-forms` field: it extends {@link HubFieldControl}, so it binds with
+ * `formControlName` / `ngModel` and shares the label, helper text and validation chrome with every
+ * other control.
+ *
+ * The **form value stays native** — a `File` in single mode, a `File[]` in multiple mode, `null`
+ * when empty — so it can be handed straight to a `FormData`. The rich per-file state (preview URL,
+ * upload status, progress, error) lives in the {@link files} signal instead of contaminating the
+ * control.
+ *
+ * Constraints declared as inputs (`accept`, `maxSize`, `minSize`, `maxTotalSize`, `maxFiles`) act as
+ * a **filter**: an offending file never reaches the value and surfaces through {@link rejected}.
+ * They are enforced by hand rather than delegated to the native `accept` attribute, which only
+ * filters the operating-system dialog and is bypassed entirely by a drop or a paste. To make the
+ * *control itself* invalid — the right choice when a value can also be patched in programmatically —
+ * add the matching validators (`hubAcceptedFiles`, `hubMaxFileSize`, …).
+ *
+ * Uploading is opt-in and transport-agnostic: register a {@link HubFileUploader} with
+ * `provideHubFileUploader()` and the component drives progress, cancel and retry. With no uploader
+ * registered it is a pure picker.
+ *
+ * @example
+ * ```html
+ * <hub-file-input
+ *   formControlName="attachments"
+ *   label="Attachments"
+ *   [multiple]="true"
+ *   accept="image/*,.pdf"
+ *   [maxSize]="5 * 1024 * 1024"
+ *   [maxFiles]="3"
+ *   preview="grid"
+ *   (rejected)="notify($event)"
+ * />
+ * ```
+ */
+declare class HubFileInputComponent extends HubFieldControl {
+    #private;
+    protected readonly _formTextTypes: typeof FormTextTypes;
+    protected readonly _items: _angular_core.WritableSignal<HubFileItem[]>;
+    /** Releases every object URL and aborts every in-flight upload when the field goes away. */
+    private readonly _cleanup;
+    /** Label text. */
+    readonly label: _angular_core.InputSignal<string>;
+    /** Whether more than one file can be held. Switches the control value to `File[]`. */
+    readonly multiple: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Accepted file types, e.g. `image/*,.pdf`. Enforced on drop and paste, not just in the dialog. */
+    readonly accept: _angular_core.InputSignal<string>;
+    /** Maximum size per file, in bytes. */
+    readonly maxSize: _angular_core.InputSignal<number | null>;
+    /** Minimum size per file, in bytes. Rejects the 0-byte files a failed export produces. */
+    readonly minSize: _angular_core.InputSignal<number | null>;
+    /** Maximum combined size of every held file, in bytes. */
+    readonly maxTotalSize: _angular_core.InputSignal<number | null>;
+    /** Maximum number of files. Only meaningful with `multiple`. */
+    readonly maxFiles: _angular_core.InputSignal<number | null>;
+    /** Whether files can be dropped onto the field. */
+    readonly dragDrop: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether files can be pasted into the focused field (e.g. a screenshot). */
+    readonly paste: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** How the held files are rendered: not at all, as a list, or as a thumbnail grid. */
+    readonly preview: _angular_core.InputSignal<HubFilePreview>;
+    /** Whether the same file can be selected twice (keyed on name, size and last-modified date). */
+    readonly allowDuplicates: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Opens the device camera instead of the file browser, on the platforms that support it. */
+    readonly capture: _angular_core.InputSignal<"user" | "environment" | null>;
+    /** Whether a newly accepted file starts uploading immediately. Ignored with no uploader registered. */
+    readonly autoUpload: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Overrides the "browse" button text coming from the global labels. */
+    readonly buttonLabel: _angular_core.InputSignal<string | null>;
+    /** Overrides the auto-generated hint that summarizes the active constraints. Pass `''` to hide it. */
+    readonly hint: _angular_core.InputSignal<string | null>;
+    /** Helper text shown below the control. */
+    readonly formText: _angular_core.InputSignal<string>;
+    /** Helper text placement. Only `bottom` is supported. */
+    readonly formTextType: _angular_core.InputSignal<FormTextType>;
+    /** Extra CSS classes applied to the host element. */
+    readonly classlist: _angular_core.InputSignal<string>;
+    /** Emits the native value whenever the selection changes. */
+    readonly valueChange: _angular_core.OutputEmitterRef<HubFileValue>;
+    /** Emits the files refused by the declared constraints, with the reason for each. */
+    readonly rejected: _angular_core.OutputEmitterRef<HubFileRejection[]>;
+    /** Emits the file removed from the selection. */
+    readonly fileRemoved: _angular_core.OutputEmitterRef<File>;
+    /** Emits the full item list whenever an upload changes status or progress. */
+    readonly uploadStateChange: _angular_core.OutputEmitterRef<readonly HubFileItem[]>;
+    /** The hidden native file input, kept focusable so the dropzone label activates it. */
+    protected readonly nativeInput: _angular_core.Signal<ElementRef<HTMLInputElement> | undefined>;
+    /** Projected per-file icon template. */
+    protected readonly iconTpt: _angular_core.Signal<HubFileIconDirective | undefined>;
+    /** Projected per-file preview template, replacing the built-in item rendering. */
+    protected readonly previewTpt: _angular_core.Signal<HubFilePreviewDirective | undefined>;
+    /** Whether a drag is currently hovering the dropzone. */
+    protected readonly isDragging: _angular_core.WritableSignal<boolean>;
+    /** Latest message for the screen-reader live region. */
+    protected readonly announcement: _angular_core.WritableSignal<string>;
+    /** The rich, per-file state of the current selection. */
+    readonly files: _angular_core.Signal<HubFileItem[]>;
+    /** Whether at least one file is currently uploading. Gate a submit button on this. */
+    readonly uploading: _angular_core.Signal<boolean>;
+    /** Whether an uploader is registered, which is what enables progress, cancel and retry. */
+    protected readonly hasUploader: boolean;
+    /** The resolved, localizable labels. */
+    protected readonly labels: _angular_core.Signal<ng_hub_ui_forms.HubFileInputLabels>;
+    /** Text of the browse action. */
+    protected readonly browseLabel: _angular_core.Signal<string>;
+    /** The hint summarizing the active constraints. */
+    protected readonly constraintsHint: _angular_core.Signal<string>;
+    /** Whether the dropzone currently accepts a drop. */
+    protected readonly dropEnabled: _angular_core.Signal<boolean>;
+    /**
+     * Derives the native validation errors from the held files rather than from the DOM.
+     *
+     * The hidden native input is emptied after every `change` so the same file can be picked twice,
+     * and it never sees a dropped or pasted file at all. Its `validity` therefore reports
+     * `valueMissing` even when files are held — reading it would mark a satisfied field as required.
+     *
+     * @param _target - Ignored; the file state is the source of truth.
+     */
+    protected updateNativeErrors(_target?: EventTarget | null): void;
+    /**
+     * Resolves a human-readable message for a failed upload.
+     *
+     * @param item - The item in the `error` state.
+     * @returns The error message.
+     */
+    protected errorText(item: HubFileItem): string;
+    writeValue(value: HubFileValue | FileList): void;
+    /** Opens the native file dialog. */
+    open(): void;
+    /**
+     * Removes a file from the selection, aborting its upload and releasing its preview.
+     *
+     * @param id - The id of the item to remove.
+     */
+    remove(id: string): void;
+    /** Removes every file, aborting any upload in flight. */
+    clear(): void;
+    /** Uploads every file that has not been uploaded yet. No-op without a registered uploader. */
+    upload(): void;
+    /**
+     * Aborts an in-flight upload, returning the file to the `ready` state.
+     *
+     * @param id - The id of the uploading item.
+     */
+    cancel(id: string): void;
+    /**
+     * Re-runs the upload of a file, typically after a failure.
+     *
+     * @param id - The id of the item to upload again.
+     */
+    retry(id: string): void;
+    /**
+     * Reads the files chosen through the native dialog.
+     *
+     * @param event - The `change` event of the hidden native input.
+     */
+    protected handleNativeChange(event: Event): void;
+    /**
+     * Accepts files dropped onto the dropzone.
+     *
+     * @param event - The drop event.
+     */
+    protected handleDrop(event: DragEvent): void;
+    /**
+     * Highlights the dropzone once a drag carrying files enters it.
+     *
+     * @param event - The dragenter event.
+     */
+    protected handleDragEnter(event: DragEvent): void;
+    /**
+     * Keeps the drop target alive. A `dragover` that does not call `preventDefault` refuses the drop.
+     *
+     * @param event - The dragover event.
+     */
+    protected handleDragOver(event: DragEvent): void;
+    /**
+     * Un-highlights the dropzone, but only once the drag has left it *and* all of its children.
+     *
+     * @param event - The dragleave event.
+     */
+    protected handleDragLeave(event: DragEvent): void;
+    /**
+     * Accepts files pasted into the focused field, e.g. a screenshot from the clipboard.
+     *
+     * @param event - The paste event.
+     */
+    protected handlePaste(event: ClipboardEvent): void;
+    /**
+     * Builds the context handed to a projected `hubFilePreview` template.
+     *
+     * @param item - The item being rendered.
+     * @returns The template context, complete with the actions the item needs.
+     */
+    protected previewContext(item: HubFileItem): HubFilePreviewContext;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubFileInputComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubFileInputComponent, "hub-file-input", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "maxSize": { "alias": "maxSize"; "required": false; "isSignal": true; }; "minSize": { "alias": "minSize"; "required": false; "isSignal": true; }; "maxTotalSize": { "alias": "maxTotalSize"; "required": false; "isSignal": true; }; "maxFiles": { "alias": "maxFiles"; "required": false; "isSignal": true; }; "dragDrop": { "alias": "dragDrop"; "required": false; "isSignal": true; }; "paste": { "alias": "paste"; "required": false; "isSignal": true; }; "preview": { "alias": "preview"; "required": false; "isSignal": true; }; "allowDuplicates": { "alias": "allowDuplicates"; "required": false; "isSignal": true; }; "capture": { "alias": "capture"; "required": false; "isSignal": true; }; "autoUpload": { "alias": "autoUpload"; "required": false; "isSignal": true; }; "buttonLabel": { "alias": "buttonLabel"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "formText": { "alias": "formText"; "required": false; "isSignal": true; }; "formTextType": { "alias": "formTextType"; "required": false; "isSignal": true; }; "classlist": { "alias": "classlist"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; "rejected": "rejected"; "fileRemoved": "fileRemoved"; "uploadStateChange": "uploadStateChange"; }, ["iconTpt", "previewTpt"], never, true, never>;
+}
+
 declare class NgOptionComponent implements OnInit {
     readonly value: _angular_core.InputSignal<any>;
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
@@ -1531,6 +2032,157 @@ declare class HubUcfirstPipe implements PipeTransform {
  */
 declare function hubAreEqual(primaryControlName: string, secondaryControlName: string): ValidatorFn;
 
+/**
+ * Validates that every file held by the control matches an `accept` specification.
+ *
+ * Complements the `accept` input of `<hub-file-input>`, which *filters* offending files before they
+ * reach the value. This validator instead makes the control **invalid**, which is what you want when
+ * files can also arrive from outside the component (patched value, restored draft, another control).
+ *
+ * Sets the `fileAccept` error with `{ accept, files }`, where `files` lists the offending names.
+ * An empty control is valid — pair it with `Validators.required` to demand a file.
+ *
+ * @param accept - The accept specification, e.g. `'image/*,.pdf'`.
+ * @returns A validator function for a file-valued control.
+ *
+ * @example
+ * ```ts
+ * new FormControl<File[]>([], [hubAcceptedFiles('image/*,.pdf')]);
+ * ```
+ */
+declare function hubAcceptedFiles(accept: string): ValidatorFn;
+
+/**
+ * Validates that no file held by the control exceeds a maximum size.
+ *
+ * Sets the `fileMaxSize` error with `{ max, actual, files }`, where `actual` is the size of the
+ * largest offending file and `files` lists the offending names. An empty control is valid.
+ *
+ * @param maxBytes - The maximum size per file, in bytes.
+ * @returns A validator function for a file-valued control.
+ *
+ * @example
+ * ```ts
+ * new FormControl<File | null>(null, [hubMaxFileSize(5 * 1024 * 1024)]);
+ * ```
+ */
+declare function hubMaxFileSize(maxBytes: number): ValidatorFn;
+
+/**
+ * Validates that no file held by the control falls below a minimum size.
+ *
+ * Useful to reject empty or truncated uploads (a 0-byte file is a common symptom of a failed export).
+ * Sets the `fileMinSize` error with `{ min, actual, files }`, where `actual` is the size of the
+ * smallest offending file. An empty control is valid.
+ *
+ * @param minBytes - The minimum size per file, in bytes.
+ * @returns A validator function for a file-valued control.
+ *
+ * @example
+ * ```ts
+ * new FormControl<File | null>(null, [hubMinFileSize(1)]);
+ * ```
+ */
+declare function hubMinFileSize(minBytes: number): ValidatorFn;
+
+/**
+ * Validates that the combined size of every file held by the control stays within a budget.
+ *
+ * This is the constraint a request-body limit actually enforces, and it is not implied by a
+ * per-file maximum: ten files of 2 MB pass `hubMaxFileSize(5 MB)` and still blow a 10 MB request.
+ *
+ * Sets the `fileMaxTotalSize` error with `{ max, actual }`. An empty control is valid.
+ *
+ * @param maxBytes - The maximum combined size, in bytes.
+ * @returns A validator function for a file-valued control.
+ *
+ * @example
+ * ```ts
+ * new FormControl<File[]>([], [hubMaxTotalSize(20 * 1024 * 1024)]);
+ * ```
+ */
+declare function hubMaxTotalSize(maxBytes: number): ValidatorFn;
+
+/**
+ * Validates that the control holds at most `max` files.
+ *
+ * Sets the `fileMaxFiles` error with `{ max, actual }`. An empty control is valid.
+ *
+ * @param max - The maximum number of files.
+ * @returns A validator function for a file-valued control.
+ *
+ * @example
+ * ```ts
+ * new FormControl<File[]>([], [hubMaxFiles(3)]);
+ * ```
+ */
+declare function hubMaxFiles(max: number): ValidatorFn;
+
+/**
+ * Validates that the control holds at least `min` files.
+ *
+ * Unlike the other file validators, this one **does** reject an empty control: holding zero files
+ * is precisely what a minimum forbids. It therefore subsumes `Validators.required`, and adding both
+ * only produces two errors for the same cause.
+ *
+ * Sets the `fileMinFiles` error with `{ min, actual }`.
+ *
+ * @param min - The minimum number of files.
+ * @returns A validator function for a file-valued control.
+ *
+ * @example
+ * ```ts
+ * new FormControl<File[]>([], [hubMinFiles(2)]);
+ * ```
+ */
+declare function hubMinFiles(min: number): ValidatorFn;
+
+/**
+ * Formats a byte count as human-readable text using binary multiples (1 KB = 1024 B).
+ *
+ * Values below 10 in their unit keep one decimal (`1.4 MB`); larger ones are rounded (`24 MB`).
+ * The decimal separator follows the given locale, or the runtime's default when omitted.
+ *
+ * @param bytes - The size in bytes.
+ * @param locale - BCP 47 locale used to format the number. Defaults to the runtime locale.
+ * @returns The formatted size, or an empty string when `bytes` is not a finite, non-negative number.
+ */
+declare function formatFileSize(bytes: number, locale?: string): string;
+
+/**
+ * Tests a file against an `accept` specification.
+ *
+ * The native `accept` attribute only filters the operating-system file dialog: files arriving by
+ * drag-and-drop or paste bypass it entirely. This function applies the same rules by hand, so a
+ * dropped file is held to the constraint the consumer declared.
+ *
+ * Supported tokens, comma-separated, matched case-insensitively:
+ * - an extension — `.pdf`
+ * - a wildcard MIME type — `image/*`
+ * - an exact MIME type — `application/pdf`
+ * - the catch-alls `*` and `*​/*`
+ *
+ * Note that a MIME token can never match a file the browser could not type (`file.type === ''`,
+ * common for unusual extensions); use an extension token for those.
+ *
+ * @param file - The file to test.
+ * @param accept - The `accept` specification. Empty or `*` accepts everything.
+ * @returns `true` when the file satisfies at least one token.
+ */
+declare function matchesAccept(file: File, accept: string): boolean;
+
+/**
+ * Builds the identity key used to detect duplicate selections.
+ *
+ * Two `File` objects are never referentially equal across separate drops, so identity is derived
+ * from the tuple the browser exposes: name, byte size and last-modified timestamp. Collisions are
+ * possible in theory (same name, size and mtime) but describe the same file in every practical case.
+ *
+ * @param file - The file to key.
+ * @returns A stable string key for the file.
+ */
+declare function fileKey(file: File): string;
+
 /**
  * Checks if a value is a string.
  *
@@ -1709,5 +2361,5 @@ interface HubFormControlAdapter {
  */
 declare const hubFormControlAdapter: HubFormControlAdapter;
 
-export { FormTextTypes, HUB_FORMS_CONFIG, HubAutoresizeDirective, HubDatepickerComponent, HubFieldControl, HubFieldsetComponent, HubFormComponent, HubFormControl, HubFormTextDirective, HubGroupControl, HubInputComponent, HubInputFormats, HubInputPrefixDirective, HubInputSuffixDirective, HubInvertColorPipe, HubJoinButLastPipe, HubLabelTypes, HubLegendComponent, HubLegendDirective, HubMapPipe, HubOtpInputComponent, HubSafeUrlPipe, HubSegmentedComponent, HubSelectComponent, HubSelectFormats, HubSliderComponent, HubSnakeUpperPipe, HubTextareaComponent, HubUcfirstPipe, HubValidationErrorDirective, NgClearButtonTemplateDirective, NgFooterTemplateDirective, NgHeaderTemplateDirective, NgLabelTemplateDirective, NgLoadingSpinnerTemplateDirective, NgLoadingTextTemplateDirective, NgMultiLabelTemplateDirective, NgNotFoundTemplateDirective, NgOptgroupTemplateDirective, NgOptionComponent, NgOptionTemplateDirective, NgSelectConfig, NgTagTemplateDirective, NgTypeToSearchTemplateDirective, applyMask, areEqual, camelToSnakeUpper, controlHasMinOrMaxValidator, defaultHubDatepickerConfig, defaultHubDatepickerLabels, defaultHubFormsConfig, defaultInvalidFeedback, get, getActiveElement, getMinOrMaxValueFromValidator, hubAreEqual, hubFormControlAdapter, isDefined, isMaskActive, isString, joinButLast, provideHubForms, runInZone, uuid };
-export type { FormTextType, HubDateRange, HubDateValue, HubDatepickerConfig, HubDatepickerLabels, HubDatepickerMode, HubFormControlAdapter, HubFormControlConfig, HubFormControlHandle, HubFormControlOption, HubFormsConfig, HubGroupErrorTrigger, HubInputFormat, HubLabelType, HubMaskResult, HubOtpMode, HubSegmentedOption, HubSegmentedSize, HubSelectFormat, HubSliderValue };
+export { FormTextTypes, HUB_FILE_UPLOADER, HUB_FORMS_CONFIG, HubAutoresizeDirective, HubDatepickerComponent, HubFieldControl, HubFieldsetComponent, HubFileIconDirective, HubFileInputComponent, HubFilePreviewDirective, HubFormComponent, HubFormControl, HubFormTextDirective, HubGroupControl, HubInputComponent, HubInputFormats, HubInputPrefixDirective, HubInputSuffixDirective, HubInvertColorPipe, HubJoinButLastPipe, HubLabelTypes, HubLegendComponent, HubLegendDirective, HubMapPipe, HubOtpInputComponent, HubSafeUrlPipe, HubSegmentedComponent, HubSelectComponent, HubSelectFormats, HubSliderComponent, HubSnakeUpperPipe, HubTextareaComponent, HubUcfirstPipe, HubValidationErrorDirective, NgClearButtonTemplateDirective, NgFooterTemplateDirective, NgHeaderTemplateDirective, NgLabelTemplateDirective, NgLoadingSpinnerTemplateDirective, NgLoadingTextTemplateDirective, NgMultiLabelTemplateDirective, NgNotFoundTemplateDirective, NgOptgroupTemplateDirective, NgOptionComponent, NgOptionTemplateDirective, NgSelectConfig, NgTagTemplateDirective, NgTypeToSearchTemplateDirective, applyMask, areEqual, camelToSnakeUpper, controlHasMinOrMaxValidator, defaultHubDatepickerConfig, defaultHubDatepickerLabels, defaultHubFileInputLabels, defaultHubFormsConfig, defaultInvalidFeedback, fileKey, formatFileSize, get, getActiveElement, getMinOrMaxValueFromValidator, hubAcceptedFiles, hubAreEqual, hubFormControlAdapter, hubMaxFileSize, hubMaxFiles, hubMaxTotalSize, hubMinFileSize, hubMinFiles, isDefined, isMaskActive, isString, joinButLast, matchesAccept, provideHubFileUploader, provideHubForms, runInZone, toFileArray, uuid };
+export type { FormTextType, HubDateRange, HubDateValue, HubDatepickerConfig, HubDatepickerLabels, HubDatepickerMode, HubFileConstraints, HubFileIconContext, HubFileInputLabels, HubFileItem, HubFilePreview, HubFilePreviewContext, HubFileRejection, HubFileRejectionReason, HubFileStatus, HubFileUploadEvent, HubFileUploader, HubFileValue, HubFormControlAdapter, HubFormControlConfig, HubFormControlHandle, HubFormControlOption, HubFormsConfig, HubGroupErrorTrigger, HubInputFormat, HubLabelType, HubMaskResult, HubOtpMode, HubSegmentedOption, HubSegmentedSize, HubSelectFormat, HubSliderValue };