@wildo-ai/saas-frontend-lib 1.0.1

package/dist/esm/components/form/fields/form-field-file.js

@@ -0,0 +1,833 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import React, { forwardRef, useMemo } from 'react';
+import { FrontendComponentType, CorePresetNames } from '@wildo-ai/presets-components-models';
+import { createComponentResolverWithRef } from '../../../core/components-registry/component-resolver.frontend.helper.js';
+import { useApplication } from '../../../core/runtime/useApplication.js';
+import { cn, useI18n, useIconRegistry, StandardIconReference, IconSize, useUI, LoadingSpinner } from "@wildo-ai/saas-frontend-lib";
+import { Button, ButtonVariants_Variant } from "../../../components/actions/button.js";
+import { UIBehavior, FormControlVariant, ButtonSize } from "@wildo-ai/presets-components-models";
+import { getFileMetadata, formatFileSize, isMimeTypeAllowed, getAcceptDescription, buildAcceptAttribute, FileDisplayNature, resolveFileDisplayNature, } from "@wildo-ai/zod-decorators";
+import { determineValidationMode, getZodErrorParams } from "../../../components/form/validation-errors/form-validation.js";
+/** Type guard to check if value is a single file */
+function isSingleFileValue(value) {
+    return value !== null && value !== undefined && 'fileId' in value;
+}
+/** Type guard to check if value is multiple files */
+function isMultipleFileValue(value) {
+    return value !== null && value !== undefined && 'fileIds' in value;
+}
+/** Generate a temporary ID for tracking uploads before server assigns fileId */
+let tempIdCounter = 0;
+function generateTempId() {
+    return `upload-${Date.now()}-${++tempIdCounter}`;
+}
+/**
+ * Detect if an error was caused by intentional cancellation (AbortController.abort).
+ *
+ * Axios throws CanceledError with code 'ERR_CANCELED' and message 'canceled'.
+ * Native fetch/AbortController throws DOMException with name 'AbortError'.
+ * We check both to remain HTTP-client-agnostic.
+ */
+function isCancellationError(err) {
+    if (!(err instanceof Error))
+        return false;
+    if (err.code === 'ERR_CANCELED')
+        return true;
+    if (err.name === 'AbortError')
+        return true;
+    return false;
+}
+function resolveSingleFileUploadUrl(endpoints, currentFileId) {
+    return currentFileId && endpoints.override
+        ? endpoints.override
+        : endpoints.upload;
+}
+function hasActionableSingleFileEndpoint(endpoints, currentFileId) {
+    return Boolean(resolveSingleFileUploadUrl(endpoints, currentFileId));
+}
+function hasActionableMultipleFileEndpoint(endpoints) {
+    return Boolean(endpoints.upload);
+}
+function getNeutralFileAttachmentLabel(filename, t) {
+    if (filename && filename.trim() !== '') {
+        return filename;
+    }
+    // Do not expose internal file ids in fallback UI when metadata is unavailable.
+    return t('File attached') ?? 'File attached';
+}
+function getSafeFileMutationErrorMessage(fallbackMessage, _err) {
+    return fallbackMessage;
+}
+/**
+ * FormFieldFile component
+ *
+ * Renders a file upload field with:
+ * - Drag and drop zone
+ * - File picker button
+ * - Current file display (single mode) or file list (multiple mode)
+ * - Replace/remove options
+ * - Progress tracking per upload
+ * - Upload cancellation support
+ */
+export const FormFieldFile_Preset_Default = React.forwardRef(({ schema, name, value: controlledValue, onChange, onBlur, defaultValue, disabled = false, readOnly, className, validationMode: validationModeProp, endpoints, uploadButtonText, replaceButtonText, onValidationError, required, httpOperations, }, ref) => {
+    const { t, tErrorValidation, tComponent, isReady } = useI18n({
+        component: FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE,
+        keys: ['errors_validation'],
+    });
+    const { renderIcon } = useIconRegistry();
+    const { getRecipe } = useUI();
+    const formRecipe = getRecipe(UIBehavior.FORM_CONTROL, FormControlVariant.DEFAULT);
+    const resolvedUploadButtonText = uploadButtonText ?? tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'choose_file');
+    const resolvedReplaceButtonText = replaceButtonText ?? tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'replace');
+    const dragDropLabel = tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'drag_and_drop');
+    const removeLabel = tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'remove');
+    const uploadFailedMessage = tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'upload_failed');
+    const metadataLoadFailedMessage = t('Unable to load file details') ?? 'Unable to load file details';
+    // Get file metadata from schema
+    const fileSchemaMetadata = getFileMetadata(schema);
+    // Get options from metadata
+    const allowedMimeTypes = fileSchemaMetadata?.allowedMimeTypes;
+    const maxSize = fileSchemaMetadata?.maxSize;
+    const minSize = fileSchemaMetadata?.minSize;
+    const overridable = fileSchemaMetadata?.overridable ?? true;
+    const accept = allowedMimeTypes ? buildAcceptAttribute(allowedMimeTypes) : undefined;
+    const isMultiple = fileSchemaMetadata?.multiple ?? false;
+    const maxFiles = fileSchemaMetadata?.maxFiles;
+    const imageConstraints = fileSchemaMetadata?.imageConstraints;
+    const videoConstraints = fileSchemaMetadata?.videoConstraints;
+    const audioConstraints = fileSchemaMetadata?.audioConstraints;
+    const documentConstraints = fileSchemaMetadata?.documentConstraints;
+    // Determine validation mode
+    const validationMode = determineValidationMode(schema, validationModeProp);
+    // Internal state for uncontrolled mode
+    const [internalValue, setInternalValue] = React.useState(defaultValue ?? null);
+    // Internal validation error state (Hybrid Pattern - see file header comment)
+    const [internalError, setInternalError] = React.useState();
+    // P1-T09: Propagate internal errors to parent (FormField) for RHF sync
+    React.useEffect(() => {
+        onValidationError?.(internalError);
+    }, [internalError, onValidationError]);
+    // Clear internal error when value is cleared (form reset or manual clear)
+    const prevValueRef = React.useRef(controlledValue);
+    React.useEffect(() => {
+        const prevValue = prevValueRef.current;
+        const valueCleared = prevValue !== undefined && (controlledValue === null || controlledValue === undefined);
+        if (valueCleared && internalError) {
+            setInternalError(undefined);
+        }
+        prevValueRef.current = controlledValue;
+    }, [controlledValue, internalError]);
+    // Upload state — supports parallel uploads for multiple file mode
+    const [uploadingFiles, setUploadingFiles] = React.useState(new Map());
+    // Ref for reading upload state outside of React state updaters (e.g., to abort)
+    const uploadingFilesRef = React.useRef(uploadingFiles);
+    uploadingFilesRef.current = uploadingFiles;
+    const [uploadProgress, setUploadProgress] = React.useState(0); // Aggregate progress for single mode
+    const [fileMetadataMap, setFileMetadataMap] = React.useState(new Map());
+    const [dragOver, setDragOver] = React.useState(false);
+    // File input ref
+    const fileInputRef = React.useRef(null);
+    // Determine if controlled
+    const isControlled = controlledValue !== undefined;
+    const currentValue = isControlled ? controlledValue : internalValue;
+    // Derived state
+    const uploading = uploadingFiles.size > 0;
+    const currentFileId = isSingleFileValue(currentValue) ? currentValue.fileId : null;
+    const currentFileIds = isMultipleFileValue(currentValue) ? currentValue.fileIds : [];
+    const hasUploadCapability = isMultiple
+        ? hasActionableMultipleFileEndpoint(endpoints)
+        : hasActionableSingleFileEndpoint(endpoints, currentFileId);
+    // Ref to track latest currentFileIds — prevents stale closure in multi-file upload.
+    // Without this, two rapid batch uploads can lose IDs: Batch 1 and Batch 2 both capture
+    // the same currentFileIds from the closure, then Batch 2's result overwrites Batch 1's.
+    const currentFileIdsRef = React.useRef(currentFileIds);
+    currentFileIdsRef.current = currentFileIds;
+    // Stable key for metadata fetch dependency (avoids inline .join() in effect deps)
+    const fileIdsKey = React.useMemo(() => currentFileIds.join(','), [currentFileIds]);
+    // Ref for metadata map to avoid stale reads in fetch effect cache check
+    const fileMetadataMapRef = React.useRef(fileMetadataMap);
+    fileMetadataMapRef.current = fileMetadataMap;
+    // Get first metadata for single file mode display
+    const fileMetadata = currentFileId ? fileMetadataMap.get(currentFileId) ?? null : null;
+    // ==========================================================================
+    // HTTP OPERATIONS — delegates to the injected httpOperations interface
+    // ==========================================================================
+    const authenticatedGet = React.useCallback(async (url) => httpOperations.get(url), [httpOperations]);
+    const authenticatedDelete = React.useCallback(async (url) => httpOperations.delete(url), [httpOperations]);
+    // ==========================================================================
+    // METADATA FETCHING — for existing files
+    // ==========================================================================
+    React.useEffect(() => {
+        if (!endpoints.getMetadata)
+            return;
+        // Determine which fileIds need metadata fetched
+        const idsToFetch = [];
+        if (currentFileId) {
+            idsToFetch.push(currentFileId);
+        }
+        if (currentFileIds.length > 0) {
+            idsToFetch.push(...currentFileIds);
+        }
+        if (idsToFetch.length === 0) {
+            setFileMetadataMap(new Map());
+            setInternalError((current) => current === metadataLoadFailedMessage ? undefined : current);
+            return;
+        }
+        let cancelled = false;
+        const fetchAll = async () => {
+            const newMap = new Map();
+            let metadataFetchFailed = false;
+            // Read from ref to get the latest cached metadata (avoids stale closure)
+            const cachedMap = fileMetadataMapRef.current;
+            await Promise.allSettled(idsToFetch.map(async (fileId) => {
+                // Skip if we already have metadata for this file (read from ref for freshness)
+                if (cachedMap.has(fileId)) {
+                    newMap.set(fileId, cachedMap.get(fileId));
+                    return;
+                }
+                try {
+                    // Build URL: endpoints.getMetadata is a template base, append /{fileId}/metadata
+                    // Backend route: GET /files/:fileId/metadata
+                    const url = `${endpoints.getMetadata}/${encodeURIComponent(fileId)}/metadata`;
+                    const data = await authenticatedGet(url);
+                    if (!cancelled) {
+                        newMap.set(fileId, data);
+                    }
+                }
+                catch {
+                    metadataFetchFailed = true;
+                    console.warn('Unable to load file metadata for one or more files.');
+                }
+            }));
+            if (!cancelled) {
+                setFileMetadataMap(newMap);
+                setInternalError((current) => (metadataFetchFailed
+                    ? metadataLoadFailedMessage
+                    : (current === metadataLoadFailedMessage ? undefined : current)));
+            }
+        };
+        fetchAll();
+        return () => { cancelled = true; };
+    }, [currentFileId, fileIdsKey, endpoints.getMetadata, authenticatedGet, metadataLoadFailedMessage]);
+    // ==========================================================================
+    // VALIDATION
+    // ==========================================================================
+    const validateFile = React.useCallback((file) => {
+        // Check MIME type
+        if (allowedMimeTypes && allowedMimeTypes.length > 0) {
+            if (!isMimeTypeAllowed(file.type, allowedMimeTypes)) {
+                const accepted = getAcceptDescription(allowedMimeTypes);
+                return tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'file_type_not_allowed', { accepted });
+            }
+        }
+        // Check file size — maximum
+        if (maxSize && file.size > maxSize) {
+            const max = formatFileSize(maxSize);
+            return tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'file_too_large', { max });
+        }
+        // Check file size — minimum
+        if (minSize && file.size < minSize) {
+            const min = formatFileSize(minSize);
+            return tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'file_too_small', { min });
+        }
+        return undefined;
+    }, [allowedMimeTypes, maxSize, minSize, tComponent]);
+    // ==========================================================================
+    // UPLOAD — single file
+    // ==========================================================================
+    /** Upload a single file via httpOperations */
+    const uploadSingleFile = React.useCallback(async (file, uploadUrl, isReplacing, existingFileId, onProgress, signal) => {
+        const formData = new FormData();
+        formData.append('file', file);
+        if (isReplacing && existingFileId) {
+            formData.append('fileId', existingFileId);
+        }
+        return httpOperations.upload(uploadUrl, formData, { onProgress, signal });
+    }, [httpOperations]);
+    // ==========================================================================
+    // UPLOAD HANDLERS — single mode
+    // ==========================================================================
+    const handleSingleFileUpload = React.useCallback(async (file) => {
+        const uploadUrl = resolveSingleFileUploadUrl(endpoints, currentFileId);
+        if (!uploadUrl) {
+            setInternalError(t('File uploads are unavailable for this field') ?? 'File uploads are unavailable for this field');
+            return;
+        }
+        // Validate first
+        const validationError = validateFile(file);
+        if (validationError) {
+            setInternalError(validationError);
+            return;
+        }
+        const tempId = generateTempId();
+        const abortController = new AbortController();
+        setUploadingFiles(new Map([[tempId, {
+                    tempId,
+                    fileName: file.name,
+                    progress: 0,
+                    status: 'uploading',
+                    abortController,
+                }]]));
+        setUploadProgress(0);
+        setInternalError(undefined);
+        try {
+            const isReplacing = !!currentFileId;
+            const result = await uploadSingleFile(file, uploadUrl, isReplacing, currentFileId, (percent) => {
+                setUploadProgress(percent);
+                setUploadingFiles(prev => {
+                    const next = new Map(prev);
+                    const state = next.get(tempId);
+                    if (state)
+                        next.set(tempId, { ...state, progress: percent });
+                    return next;
+                });
+            }, abortController.signal);
+            // Build new value
+            const newValue = {
+                fileId: result.fileId,
+                updatedAt: new Date(),
+            };
+            if (!isControlled) {
+                setInternalValue(newValue);
+            }
+            onChange?.(newValue);
+            // Update metadata cache
+            if (result.metadata) {
+                setFileMetadataMap(prev => {
+                    const next = new Map(prev);
+                    next.set(result.fileId, result.metadata);
+                    return next;
+                });
+            }
+            // Validate the new value against schema
+            if (validationMode !== 'onSubmit') {
+                const schemaResult = schema.safeParse(newValue);
+                if (!schemaResult.success) {
+                    const firstIssue = schemaResult.error.issues[0];
+                    if (firstIssue) {
+                        const params = { ...getZodErrorParams(firstIssue), message: firstIssue.message };
+                        const translated = tErrorValidation(firstIssue.code, 'msg', params);
+                        setInternalError(translated);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (isCancellationError(err))
+                return;
+            setInternalError(getSafeFileMutationErrorMessage(uploadFailedMessage, err));
+        }
+        finally {
+            setUploadingFiles(new Map());
+            setUploadProgress(0);
+        }
+    }, [currentFileId, endpoints, isControlled, onChange, t, validateFile, validationMode, schema, tErrorValidation, uploadSingleFile]);
+    // ==========================================================================
+    // UPLOAD HANDLERS — multiple mode
+    // ==========================================================================
+    const handleMultipleFilesUpload = React.useCallback(async (files) => {
+        if (!hasActionableMultipleFileEndpoint(endpoints)) {
+            setInternalError(t('File uploads are unavailable for this field') ?? 'File uploads are unavailable for this field');
+            return;
+        }
+        // Use ref to get latest file IDs — prevents stale closure when batches overlap.
+        // Without this, two rapid uploads both see the same old currentFileIds,
+        // and the second batch's result would overwrite the first batch's new IDs.
+        const latestFileIds = currentFileIdsRef.current;
+        // Validate all files first
+        const currentCount = latestFileIds.length;
+        if (maxFiles && currentCount + files.length > maxFiles) {
+            setInternalError(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'too_many_files', { max: maxFiles }));
+            return;
+        }
+        const validFiles = [];
+        for (const file of files) {
+            const error = validateFile(file);
+            if (error) {
+                setInternalError(error);
+                return;
+            }
+            validFiles.push(file);
+        }
+        setInternalError(undefined);
+        // Create upload state for each file
+        const initialStates = new Map();
+        const fileEntries = [];
+        for (const file of validFiles) {
+            const tempId = generateTempId();
+            const abortController = new AbortController();
+            initialStates.set(tempId, {
+                tempId,
+                fileName: file.name,
+                progress: 0,
+                status: 'uploading',
+                abortController,
+            });
+            fileEntries.push({ tempId, file, abortController });
+        }
+        setUploadingFiles(prev => {
+            const next = new Map();
+            // Keep only in-progress uploads from previous batches; discard stale errors
+            for (const [id, state] of prev) {
+                if (state.status === 'uploading') {
+                    next.set(id, state);
+                }
+            }
+            // Add new uploads
+            for (const [id, state] of initialStates) {
+                next.set(id, state);
+            }
+            return next;
+        });
+        // Upload all files in parallel
+        const results = await Promise.allSettled(fileEntries.map(async ({ tempId, file, abortController }) => {
+            try {
+                const result = await uploadSingleFile(file, endpoints.upload, false, null, (percent) => {
+                    setUploadingFiles(prev => {
+                        const next = new Map(prev);
+                        const state = next.get(tempId);
+                        if (state)
+                            next.set(tempId, { ...state, progress: percent });
+                        return next;
+                    });
+                }, abortController.signal);
+                // Mark as done
+                setUploadingFiles(prev => {
+                    const next = new Map(prev);
+                    const state = next.get(tempId);
+                    if (state)
+                        next.set(tempId, { ...state, status: 'done', fileId: result.fileId, progress: 100 });
+                    return next;
+                });
+                // Cache metadata
+                if (result.metadata) {
+                    setFileMetadataMap(prev => {
+                        const next = new Map(prev);
+                        next.set(result.fileId, result.metadata);
+                        return next;
+                    });
+                }
+                return result.fileId;
+            }
+            catch (err) {
+                if (isCancellationError(err)) {
+                    setUploadingFiles(prev => {
+                        const next = new Map(prev);
+                        next.delete(tempId);
+                        return next;
+                    });
+                    throw err;
+                }
+                setUploadingFiles(prev => {
+                    const next = new Map(prev);
+                    const state = next.get(tempId);
+                    if (state)
+                        next.set(tempId, {
+                            ...state,
+                            status: 'error',
+                            error: getSafeFileMutationErrorMessage(uploadFailedMessage, err)
+                        });
+                    return next;
+                });
+                throw err;
+            }
+        }));
+        // Collect successful fileIds
+        const newFileIds = [];
+        for (const result of results) {
+            if (result.status === 'fulfilled') {
+                newFileIds.push(result.value);
+            }
+        }
+        if (newFileIds.length > 0) {
+            // Read latest file IDs via ref to avoid stale closure
+            const updatedFileIds = [...currentFileIdsRef.current, ...newFileIds];
+            const newValue = {
+                fileIds: updatedFileIds,
+                updatedAt: new Date(),
+            };
+            if (!isControlled) {
+                setInternalValue(newValue);
+            }
+            onChange?.(newValue);
+        }
+        // Report errors if any uploads failed (exclude intentional cancellations)
+        const failedCount = results.filter(r => r.status === 'rejected' && !isCancellationError(r.reason)).length;
+        if (failedCount > 0 && failedCount < files.length) {
+            setInternalError(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'some_uploads_failed', { failed: failedCount, total: files.length }));
+        }
+        else if (failedCount === files.length) {
+            setInternalError(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'upload_failed'));
+        }
+        // Clear completed uploads from state (keep errors for display)
+        setUploadingFiles(prev => {
+            const next = new Map(prev);
+            for (const [id, state] of next) {
+                if (state.status === 'done')
+                    next.delete(id);
+            }
+            return next;
+        });
+    }, [endpoints, isControlled, maxFiles, onChange, tComponent, uploadSingleFile, validateFile, uploadFailedMessage]);
+    // ==========================================================================
+    // UNIFIED FILE HANDLER
+    // ==========================================================================
+    const handleFiles = React.useCallback((files) => {
+        if (files.length === 0)
+            return;
+        if (isMultiple) {
+            handleMultipleFilesUpload(files);
+        }
+        else {
+            handleSingleFileUpload(files[0]);
+        }
+    }, [isMultiple, handleMultipleFilesUpload, handleSingleFileUpload]);
+    // Handle file input change
+    const handleFileChange = React.useCallback((e) => {
+        const files = e.target.files;
+        if (files && files.length > 0) {
+            handleFiles(Array.from(files));
+        }
+        // Reset input so same file can be selected again
+        if (fileInputRef.current) {
+            fileInputRef.current.value = '';
+        }
+    }, [handleFiles]);
+    // Effective disabled includes readOnly for interactive elements
+    const isInteractionDisabled = disabled || readOnly;
+    const isUploadInteractionDisabled = isInteractionDisabled || !hasUploadCapability;
+    // Handle drag and drop
+    const handleDragOver = React.useCallback((e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        if (!isUploadInteractionDisabled && !uploading) {
+            setDragOver(true);
+        }
+    }, [isUploadInteractionDisabled, uploading]);
+    const handleDragLeave = React.useCallback((e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        setDragOver(false);
+    }, []);
+    const handleDrop = React.useCallback((e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        setDragOver(false);
+        if (isUploadInteractionDisabled || uploading)
+            return;
+        const files = e.dataTransfer.files;
+        if (files && files.length > 0) {
+            handleFiles(Array.from(files));
+        }
+    }, [isUploadInteractionDisabled, uploading, handleFiles]);
+    // Handle remove single file
+    const handleRemoveSingle = React.useCallback(async () => {
+        if (!currentFileId)
+            return;
+        if (endpoints.delete) {
+            try {
+                // Backend route: DELETE /files/:fileId
+                const url = `${endpoints.delete}/${encodeURIComponent(currentFileId)}`;
+                await authenticatedDelete(url);
+            }
+            catch (err) {
+                if (isCancellationError(err))
+                    return;
+                setInternalError(getSafeFileMutationErrorMessage(uploadFailedMessage, err));
+                return;
+            }
+        }
+        setInternalError(undefined);
+        if (!isControlled) {
+            setInternalValue(null);
+        }
+        onChange?.(null);
+        setFileMetadataMap(prev => {
+            const next = new Map(prev);
+            next.delete(currentFileId);
+            return next;
+        });
+    }, [currentFileId, endpoints, isControlled, onChange, authenticatedDelete, uploadFailedMessage]);
+    // Handle remove file from multiple list.
+    // Uses currentFileIdsRef to avoid stale closure: two rapid removes would both
+    // capture the same closure value, and the second would re-add the file removed by the first.
+    const handleRemoveFromMultiple = React.useCallback(async (fileId) => {
+        if (endpoints.delete) {
+            try {
+                const url = `${endpoints.delete}/${encodeURIComponent(fileId)}`;
+                await authenticatedDelete(url);
+            }
+            catch (err) {
+                if (isCancellationError(err))
+                    return;
+                setInternalError(getSafeFileMutationErrorMessage(uploadFailedMessage, err));
+                return;
+            }
+        }
+        setInternalError(undefined);
+        // Read latest file IDs via ref — prevents lost removals during rapid clicks
+        const updatedIds = currentFileIdsRef.current.filter(id => id !== fileId);
+        const newValue = updatedIds.length > 0
+            ? { fileIds: updatedIds, updatedAt: new Date() }
+            : null;
+        if (!isControlled) {
+            setInternalValue(newValue);
+        }
+        onChange?.(newValue);
+        setFileMetadataMap(prev => {
+            const next = new Map(prev);
+            next.delete(fileId);
+            return next;
+        });
+    }, [endpoints, isControlled, onChange, authenticatedDelete, uploadFailedMessage]);
+    // Cancel a specific upload.
+    // Side effect (abort) is performed BEFORE the state update to comply with
+    // React's requirement that state updater functions be pure.
+    const handleCancelUpload = React.useCallback((tempId) => {
+        // Read current state via ref (no side effect inside updater)
+        const state = uploadingFilesRef.current.get(tempId);
+        if (state) {
+            state.abortController.abort();
+        }
+        setUploadingFiles(prev => {
+            const next = new Map(prev);
+            next.delete(tempId);
+            return next;
+        });
+    }, []);
+    // Handle click on drop zone
+    const handleClick = React.useCallback(() => {
+        if (!isUploadInteractionDisabled && !uploading) {
+            fileInputRef.current?.click();
+        }
+    }, [isUploadInteractionDisabled, uploading]);
+    // Get file icon reference based on MIME type (consistent with display-field-file.tsx)
+    const getFileIconRef = (mimeType) => {
+        if (!mimeType)
+            return StandardIconReference.FILE;
+        if (mimeType.startsWith('image/'))
+            return StandardIconReference.FILE_IMAGE;
+        if (mimeType.startsWith('video/'))
+            return StandardIconReference.FILE_VIDEO;
+        if (mimeType.startsWith('audio/'))
+            return StandardIconReference.FILE_AUDIO;
+        if (mimeType === 'application/pdf')
+            return StandardIconReference.FILE_TEXT;
+        if (mimeType.includes('spreadsheet') || mimeType.includes('excel'))
+            return StandardIconReference.FILE_SPREADSHEET;
+        if (mimeType.includes('presentation') || mimeType.includes('powerpoint'))
+            return StandardIconReference.FILE_PRESENTATION;
+        if (mimeType.includes('document') || mimeType.includes('word'))
+            return StandardIconReference.FILE_TEXT;
+        if (mimeType.includes('zip') || mimeType.includes('rar') || mimeType.includes('7z'))
+            return StandardIconReference.FILE_ARCHIVE;
+        return StandardIconReference.FILE;
+    };
+    /** Render a file icon for the given MIME type at the specified size */
+    const renderFileIcon = (mimeType, size = IconSize.MD) => {
+        return renderIcon(getFileIconRef(mimeType), { size });
+    };
+    const acceptDescription = getAcceptDescription(allowedMimeTypes);
+    // ==========================================================================
+    // RENDER — Nature detection for preview routing
+    // ==========================================================================
+    /** Resolve the display nature using the shared utility from zod-decorators */
+    const schemaNature = fileSchemaMetadata?.nature;
+    // ==========================================================================
+    // RENDER — File action buttons (shared between single + multi displays)
+    // ==========================================================================
+    const renderFileActions = (onRemove, compact = false) => (!isInteractionDisabled ? (_jsxs("div", { className: cn("flex items-center gap-element", compact ? "flex-shrink-0" : ""), children: [!compact && overridable && hasUploadCapability && (_jsx(Button, { type: "button", variant: ButtonVariants_Variant.OUTLINE, size: ButtonSize.SM, onClick: handleClick, disabled: uploading, children: resolvedReplaceButtonText })), _jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.SM, onClick: onRemove, disabled: uploading, className: cn("text-destructive hover:text-destructive", compact && "h-6 w-6 p-0"), "aria-label": removeLabel, title: removeLabel, children: renderIcon(StandardIconReference.CLOSE, { size: IconSize.SM }) })] })) : null);
+    // ==========================================================================
+    // RENDER — File info line (filename, size, extension — shared)
+    // ==========================================================================
+    const renderFileInfo = (fileId, meta, compact = false) => (_jsxs("div", { className: cn("min-w-0", compact ? "" : "flex-1"), children: [_jsx("div", { className: "flex items-center gap-element", children: meta?.url ? (_jsx("a", { href: meta.url, target: "_blank", rel: "noopener noreferrer", className: cn("font-medium text-primary hover:underline truncate", compact && "text-sm"), children: meta.filename })) : (_jsx("span", { className: cn("font-medium truncate", compact && "text-sm"), children: getNeutralFileAttachmentLabel(meta?.filename, t) })) }), _jsxs("div", { className: "flex items-center gap-group text-xs text-muted-foreground mt-0.5", children: [meta?.size !== undefined && (_jsx("span", { children: formatFileSize(meta.size) })), meta?.mimeType && (_jsx("span", { className: "uppercase", children: meta.extension || meta.mimeType.split('/').pop() })), meta?.width && meta?.height && (_jsxs("span", { children: [meta.width, "\u00D7", meta.height] }))] })] }));
+    // ==========================================================================
+    // RENDER — Nature-specific previews
+    // ==========================================================================
+    const renderImagePreview = (meta) => (_jsxs("div", { className: "rounded-md border bg-muted/30 overflow-hidden", children: [_jsx("div", { className: "relative", children: _jsx("img", { src: meta.url || meta.thumbnailUrl || '', alt: meta.filename, className: "w-full max-h-64 object-contain bg-checkerboard", loading: "lazy", onError: (e) => { e.target.style.display = 'none'; } }) }), _jsxs("div", { className: "flex items-center gap-group p-card-sm", children: [_jsx("span", { "aria-hidden": "true", children: renderFileIcon(meta.mimeType, IconSize.MD) }), renderFileInfo('', meta), renderFileActions(handleRemoveSingle)] })] }));
+    const renderVideoPreview = (meta) => (_jsxs("div", { className: "rounded-md border bg-muted/30 overflow-hidden", children: [_jsx("video", { src: meta.url, controls: true, className: "w-full max-h-64 bg-black", poster: meta.thumbnailUrl, preload: "metadata" }), _jsxs("div", { className: "flex items-center gap-group p-card-sm", children: [_jsx("span", { "aria-hidden": "true", children: renderFileIcon(meta.mimeType, IconSize.MD) }), renderFileInfo('', meta), renderFileActions(handleRemoveSingle)] })] }));
+    const renderAudioPreview = (meta) => (_jsxs("div", { className: "rounded-md border bg-muted/30 p-card-sm space-y-element", children: [_jsxs("div", { className: "flex items-center gap-group", children: [_jsx("span", { "aria-hidden": "true", children: renderFileIcon(meta.mimeType, IconSize.MD) }), renderFileInfo('', meta), renderFileActions(handleRemoveSingle)] }), _jsx("audio", { src: meta.url, controls: true, className: "w-full h-8", preload: "metadata" })] }));
+    // ==========================================================================
+    // RENDER — Single file display (nature-aware)
+    // ==========================================================================
+    const renderSingleFileDisplay = (fileId, meta) => {
+        if (!meta) {
+            // No metadata yet — show generic card
+            return (_jsxs("div", { className: "flex items-center gap-group p-card-sm rounded-md border bg-muted/30", children: [_jsx("span", { "aria-hidden": "true", children: renderFileIcon(undefined, IconSize.LG) }), renderFileInfo(fileId, null), renderFileActions(handleRemoveSingle)] }));
+        }
+        const nature = resolveFileDisplayNature(schemaNature, meta.mimeType);
+        // Nature-specific rendering
+        if (nature === FileDisplayNature.IMAGE && (meta.url || meta.thumbnailUrl)) {
+            return renderImagePreview(meta);
+        }
+        if (nature === FileDisplayNature.VIDEO && meta.url) {
+            return renderVideoPreview(meta);
+        }
+        if (nature === FileDisplayNature.AUDIO && meta.url) {
+            return renderAudioPreview(meta);
+        }
+        // Generic / document fallback — compact card
+        return (_jsxs("div", { className: "flex items-center gap-group p-card-sm rounded-md border bg-muted/30", children: [_jsx("span", { "aria-hidden": "true", children: renderFileIcon(meta.mimeType, IconSize.LG) }), renderFileInfo(fileId, meta), renderFileActions(handleRemoveSingle)] }));
+    };
+    // ==========================================================================
+    // RENDER — Multiple file list
+    // ==========================================================================
+    /** Render a single item within the multiple-file list */
+    const renderMultipleFileItem = (fileId, meta) => {
+        const nature = resolveFileDisplayNature(schemaNature, meta?.mimeType);
+        const onRemove = () => handleRemoveFromMultiple(fileId);
+        // Compact image preview — thumbnail inline
+        if (nature === FileDisplayNature.IMAGE && meta && (meta.url || meta.thumbnailUrl)) {
+            return (_jsxs("div", { className: "flex items-center gap-group p-card-sm rounded-md border bg-muted/30", children: [_jsx("img", { src: meta.thumbnailUrl || meta.url || '', alt: meta.filename, className: "h-12 w-12 rounded object-cover flex-shrink-0", loading: "lazy", onError: (e) => { e.target.style.display = 'none'; } }), _jsx("div", { className: "flex-1 min-w-0", children: renderFileInfo(fileId, meta, true) }), renderFileActions(onRemove, true)] }, fileId));
+        }
+        // Compact audio preview — inline player
+        if (nature === FileDisplayNature.AUDIO && meta?.url) {
+            return (_jsxs("div", { className: "rounded-md border bg-muted/30 p-card-sm space-y-item-xs", children: [_jsxs("div", { className: "flex items-center gap-group", children: [_jsx("span", { "aria-hidden": "true", children: renderFileIcon(meta.mimeType, IconSize.MD) }), _jsx("div", { className: "flex-1 min-w-0", children: renderFileInfo(fileId, meta, true) }), renderFileActions(onRemove, true)] }), _jsx("audio", { src: meta.url, controls: true, className: "w-full h-8", preload: "metadata" })] }, fileId));
+        }
+        // Generic compact card (video, document, unknown)
+        return (_jsxs("div", { className: "flex items-center gap-group p-card-sm rounded-md border bg-muted/30", children: [_jsx("span", { "aria-hidden": "true", children: renderFileIcon(meta?.mimeType, IconSize.MD) }), _jsx("div", { className: "flex-1 min-w-0", children: renderFileInfo(fileId, meta ?? null, true) }), renderFileActions(onRemove, true)] }, fileId));
+    };
+    const renderMultipleFileList = () => (_jsxs("div", { className: "space-y-element", children: [currentFileIds.map((fileId) => {
+                const meta = fileMetadataMap.get(fileId);
+                return renderMultipleFileItem(fileId, meta);
+            }), Array.from(uploadingFiles.values()).map((uploadState) => (_jsxs("div", { className: "flex items-center gap-group p-card-sm rounded-md border border-primary/20 bg-primary/5", children: [uploadState.status === 'uploading' && (_jsx(LoadingSpinner, { size: 20, className: "text-primary flex-shrink-0", "aria-hidden": "true" })), uploadState.status === 'error' && (_jsx("span", { className: "text-destructive flex-shrink-0", "aria-hidden": "true", children: renderIcon(StandardIconReference.WARNING, { size: IconSize.MD }) })), _jsxs("div", { className: "flex-1 min-w-0", children: [_jsx("span", { className: "font-medium text-sm truncate block", children: uploadState.fileName }), uploadState.status === 'uploading' && (_jsx("div", { className: "w-full h-1 bg-muted rounded-full mt-1 overflow-hidden", children: uploadState.progress < 0 ? (_jsx("div", { className: "h-full w-1/3 bg-primary animate-pulse rounded-full" })) : (_jsx("div", { className: "h-full bg-primary transition-all duration-[var(--motion-duration-fast)]", style: { width: `${uploadState.progress}%` } })) })), uploadState.status === 'error' && uploadState.error && (_jsx("span", { className: "text-xs text-destructive", children: uploadState.error }))] }), uploadState.status === 'uploading' && (_jsx(Button, { type: "button", variant: ButtonVariants_Variant.GHOST, size: ButtonSize.SM, onClick: () => handleCancelUpload(uploadState.tempId), className: "text-muted-foreground hover:text-destructive h-6 w-6 p-0", "aria-label": tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'cancel'), title: tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'cancel'), children: renderIcon(StandardIconReference.CLOSE, { size: IconSize.SM }) }))] }, uploadState.tempId)))] }));
+    // ==========================================================================
+    // RENDER — Constraint hints (below upload area)
+    // ==========================================================================
+    /** Format seconds into human-readable duration */
+    const formatDuration = (seconds) => {
+        if (seconds < 60)
+            return `${seconds}s`;
+        if (seconds < 3600)
+            return `${Math.floor(seconds / 60)} min`;
+        const h = Math.floor(seconds / 3600);
+        const m = Math.floor((seconds % 3600) / 60);
+        return m > 0 ? `${h}h ${m}min` : `${h}h`;
+    };
+    const constraintHints = React.useMemo(() => {
+        const hints = [];
+        // Size constraints
+        if (minSize && maxSize) {
+            hints.push(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'constraint_size_range', { min: formatFileSize(minSize), max: formatFileSize(maxSize) }));
+        }
+        else if (minSize) {
+            hints.push(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'constraint_min_size', { min: formatFileSize(minSize) }));
+        }
+        // maxSize is already shown inline in the upload zone — no duplicate needed
+        // Image constraints
+        if (imageConstraints) {
+            const { minWidth, maxWidth, minHeight, maxHeight, aspectRatio } = imageConstraints;
+            if (minWidth || minHeight) {
+                const w = minWidth ?? '–';
+                const h = minHeight ?? '–';
+                hints.push(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'constraint_image_dimensions', { width: String(w), height: String(h) }));
+            }
+            if (maxWidth || maxHeight) {
+                const w = maxWidth ?? '–';
+                const h = maxHeight ?? '–';
+                hints.push(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'constraint_image_max_dimensions', { width: String(w), height: String(h) }));
+            }
+            if (aspectRatio) {
+                hints.push(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'constraint_image_aspect_ratio', { width: String(aspectRatio.width), height: String(aspectRatio.height) }));
+            }
+        }
+        // Video constraints
+        if (videoConstraints) {
+            if (videoConstraints.maxDuration) {
+                hints.push(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'constraint_video_max_duration', { duration: formatDuration(videoConstraints.maxDuration) }));
+            }
+        }
+        // Audio constraints
+        if (audioConstraints) {
+            if (audioConstraints.maxDuration) {
+                hints.push(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'constraint_audio_max_duration', { duration: formatDuration(audioConstraints.maxDuration) }));
+            }
+        }
+        // Document constraints
+        if (documentConstraints) {
+            if (documentConstraints.maxPages) {
+                hints.push(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'constraint_document_max_pages', { pages: documentConstraints.maxPages }));
+            }
+        }
+        // Multiple file constraint
+        if (isMultiple && maxFiles) {
+            hints.push(tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'constraint_max_files', { max: maxFiles }));
+        }
+        return hints;
+    }, [minSize, maxSize, imageConstraints, videoConstraints, audioConstraints, documentConstraints, isMultiple, maxFiles, tComponent]);
+    const renderConstraintHints = () => {
+        if (constraintHints.length === 0)
+            return null;
+        return (_jsx("div", { className: "flex flex-wrap gap-x-group gap-y-item-xs mt-item-xs", children: constraintHints.map((hint, i) => (_jsx("span", { className: "text-xs text-muted-foreground", children: hint }, i))) }));
+    };
+    // ==========================================================================
+    // RENDER — Upload zone (drop target + button)
+    // ==========================================================================
+    const renderUploadZone = (compact = false) => (_jsx("div", { onClick: handleClick, onDragOver: handleDragOver, onDragLeave: handleDragLeave, onDrop: handleDrop, className: cn("relative flex flex-col items-center justify-center rounded-md border-2 border-dashed cursor-pointer", compact ? "p-card-sm" : "p-container", dragOver && "border-primary bg-primary/5", isUploadInteractionDisabled && "opacity-[var(--opacity-disabled)] cursor-not-allowed", uploading && !isMultiple && "pointer-events-none", internalError && "border-destructive", !isUploadInteractionDisabled && !uploading && "hover:border-primary hover:bg-primary/5", formRecipe.motion.transition), children: uploading && !isMultiple ? (_jsxs(_Fragment, { children: [_jsx(LoadingSpinner, { size: 32, className: "text-primary mb-element", "aria-hidden": "true" }), _jsx("span", { className: "text-sm text-muted-foreground", children: uploadProgress < 0
+                        ? tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'uploading_indeterminate')
+                        : tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'uploading', { progress: uploadProgress }) }), _jsx("div", { className: "w-full max-w-xs h-1 bg-muted rounded-full mt-element overflow-hidden", children: uploadProgress < 0 ? (
+                    // Indeterminate progress: animated shimmer bar
+                    _jsx("div", { className: "h-full w-1/3 bg-primary animate-pulse rounded-full" })) : (_jsx("div", { className: "h-full bg-primary transition-all duration-[var(--motion-duration-fast)]", style: { width: `${uploadProgress}%` } })) })] })) : (_jsxs(_Fragment, { children: [!compact && _jsx("span", { className: "mb-element", "aria-hidden": "true", children: renderIcon(StandardIconReference.UPLOAD, { size: IconSize.XL }) }), _jsx("span", { className: cn("font-medium", compact ? "text-xs" : "text-sm"), children: compact ? tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'add_more') : resolvedUploadButtonText }), !compact && (_jsxs(_Fragment, { children: [_jsx("span", { className: "text-xs text-muted-foreground mt-item-xs", children: dragDropLabel }), _jsxs("span", { className: "text-xs text-muted-foreground mt-element", children: [acceptDescription, maxSize && !minSize && ` • ${tComponent(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'max_size', { size: formatFileSize(maxSize) })}`] }), renderConstraintHints()] }))] })) }));
+    // ==========================================================================
+    // RENDER — Main
+    // ==========================================================================
+    const canAddMore = isMultiple && (!maxFiles || currentFileIds.length < maxFiles);
+    if (!isReady)
+        return null;
+    return (_jsxs("div", { ref: ref, className: className, children: [_jsx("input", { ref: fileInputRef, type: "file", accept: accept, multiple: isMultiple, onChange: handleFileChange, className: "hidden", disabled: isUploadInteractionDisabled }), isMultiple ? (
+            // Multiple file mode
+            _jsxs("div", { className: "space-y-element", children: [currentFileIds.length > 0 && renderMultipleFileList(), !isUploadInteractionDisabled && canAddMore && renderUploadZone(currentFileIds.length > 0), !isUploadInteractionDisabled && currentFileIds.length === 0 && !canAddMore && renderUploadZone(false)] })) : (
+            // Single file mode
+            currentFileId
+                ? renderSingleFileDisplay(currentFileId, fileMetadata)
+                : (hasUploadCapability ? renderUploadZone(false) : null))] }));
+});
+// --- Wrapper ---
+/**
+ * Schema-aware FormFieldFile component.
+ *
+ * This wrapper sits between the generic FormField orchestrator and the preset
+ * component. It is the proper boundary for injecting engine-level concerns:
+ * - Authenticated HTTP operations (upload, metadata, delete) via httpClient
+ * - Component preset resolution via the registry
+ *
+ * The preset component (presets-components) never imports the HTTP client directly,
+ * maintaining separation of concerns. The generic FormField never deals with
+ * file-specific HTTP concerns.
+ */
+export const FormFieldFile = forwardRef(({ preset = CorePresetNames.DEFAULT, httpOperations: externalHttpOperations, ...props }, ref) => {
+    const { httpClient } = useApplication();
+    const httpOperations = useMemo(() => {
+        if (externalHttpOperations)
+            return externalHttpOperations;
+        return {
+            upload: async (url, formData, options) => {
+                const response = await httpClient.uploadFile(url, formData, {
+                    onUploadProgress: options?.onProgress,
+                    signal: options?.signal,
+                });
+                if (response?.file?.fileId) {
+                    return {
+                        fileId: response.file.fileId,
+                        metadata: response.file,
+                    };
+                }
+                if (response?.fileId) {
+                    return { fileId: response.fileId, metadata: response.metadata };
+                }
+                throw new Error('upload_failed');
+            },
+            get: async (url) => {
+                return httpClient.get(url);
+            },
+            delete: async (url) => {
+                await httpClient.delete(url);
+            },
+        };
+    }, [httpClient, externalHttpOperations]);
+    const Component = createComponentResolverWithRef(FrontendComponentType.LOW_LEVEL_FORM_FIELD_FILE, 'FormFieldFile')(preset);
+    const resolvedProps = { ...props, httpOperations };
+    return _jsx(Component, { ...resolvedProps, ref: ref });
+});
+FormFieldFile.displayName = 'FormFieldFile';
+//# sourceMappingURL=form-field-file.js.map