{
  "tag": "ed-upload",
  "kind": "component",
  "summary": "Generic file upload: drag & drop, validation and per-file upload progress.",
  "status": "experimental",
  "level": "molecule",
  "since": "1.0",
  "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/upload/",
  "usage": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/upload/usage/",
  "playwright": "getByTestId('…')",
  "dependencies": [
    "ed-button",
    "ed-icon",
    "ed-progress-bar"
  ],
  "use": [
    "Users adding one or more files by drag-and-drop or a picker who need to see each file's upload progress and final outcome",
    "Document upload in a workflow, bulk document upload, or any flow where several files are staged and uploaded with visible status",
    "Limiting uploads to certain file types and sizes, and showing the user the limits before they pick files"
  ],
  "notFor": [
    {
      "when": "A single file in a compact form field, or files picked there and submitted with the form, where a queue, progress, and status rows add nothing",
      "instead": "[File Input](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/file-input)"
    },
    {
      "when": "A plain form control that merely needs to hold a file value",
      "instead": "[File Input](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/file-input)"
    }
  ],
  "rules": [
    {
      "id": "upload/uploading-not-dropping",
      "rule": "Choose between Upload and [File Input](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/file-input) by whether the files are uploaded, never by drag-and-drop — both offer it. Upload is the richer surface, with a file list and per-file progress, sending files as they are chosen."
    },
    {
      "id": "upload/keep-the-file-button",
      "rule": "Keep both the drop zone and the visible choose-files button available, so keyboard and touch users are never blocked — never rely on the drop zone alone. Don't add your own button — the component shows both.",
      "why": "A drag-only target excludes keyboard and touch users.",
      "check": "error"
    },
    {
      "id": "upload/limits-up-front",
      "rule": "State the accepted file types and size limits up front, before the user picks — never hide them until after a file has been refused.",
      "why": "Error prevention beats after-the-fact rejection."
    },
    {
      "id": "upload/built-in-file-rows",
      "rule": "Don't build your own file status or remove action — each file's row shows its own status (waiting, uploading with a progress bar, done, or failed with a reason) and a remove action whose accessible label names the file, so it is always clear what is being removed.",
      "check": "warning"
    },
    {
      "id": "upload/retry-failed",
      "rule": "Never leave a failed upload without a way to try again. Don't add your own retry action — a failed upload offers one whenever `upload-url` is set, and `retryFile(name)` re-queues the same file from code.",
      "check": "warning"
    },
    {
      "id": "upload/recover-rejected",
      "rule": "Let a user recover a rejected file by removing it and picking a different one.",
      "why": "Validation runs on the device, so there is nothing to retry."
    },
    {
      "id": "upload/wrap-for-dialog",
      "rule": "Compose it inside a dialog when you need a modal upload experience, and wrap it yourself wherever a dialog, header, title or buttons are needed.",
      "why": "It brings no dialog, title, header, or action buttons of its own."
    }
  ],
  "api": {
    "attributes": [
      {
        "name": "multiple",
        "property": "multiple",
        "type": "boolean",
        "default": "false",
        "description": "Allow selecting/dropping more than one file (mirrors the native input's `multiple`)."
      },
      {
        "name": "accept",
        "property": "accept",
        "type": "string",
        "default": "''",
        "description": "Comma-separated list of accepted types (extensions and/or MIME types), like the native `accept`."
      },
      {
        "name": "upload-url",
        "property": "uploadUrl",
        "type": "null | string",
        "default": "null",
        "description": "Target URL the files are POSTed to."
      },
      {
        "name": "upload-file-part-name",
        "property": "uploadFilePartName",
        "type": "string",
        "default": "'file'",
        "description": "FormData part name used for each file."
      },
      {
        "name": "max-files",
        "property": "maxFiles",
        "type": "null | number",
        "default": "null",
        "description": "Maximum number of files (multi mode)."
      },
      {
        "name": "max-file-size",
        "property": "maxFileSize",
        "type": "number",
        "default": "MAX_SIZE_MB",
        "description": "Maximum size per file in MB (capped at 2048)."
      },
      {
        "name": "max-total-file-size",
        "property": "maxTotalFileSize",
        "type": "number",
        "default": "MAX_SIZE_MB",
        "description": "Maximum total upload size in MB (capped at 2048)."
      },
      {
        "name": "disabled",
        "property": "disabled",
        "type": "boolean",
        "default": "false",
        "description": "Disables interaction."
      },
      {
        "name": "viewable",
        "property": "viewable",
        "type": "boolean",
        "default": "false",
        "description": "Opt in to a per-file preview (\"view\") action in the list. When set, each row shows an eye\nbutton that emits `ed-file-preview`. While an upload is configured the button stays disabled\nuntil that file has finished uploading; without an `upload-url` it is enabled immediately."
      },
      {
        "name": "dir",
        "property": "dir",
        "type": "string"
      },
      {
        "name": "lang",
        "property": "lang",
        "type": "string"
      }
    ],
    "properties": [
      {
        "name": "headers",
        "type": "UploadHeaders",
        "description": "Request headers, either a static object or a function (sync or async) resolved per request.\nUse the function form for auth tokens so they stay fresh and never live in the DOM."
      },
      {
        "name": "files",
        "type": "UploadFileItem[]",
        "description": "The files currently held by the component."
      }
    ],
    "methods": [
      {
        "name": "retryFile",
        "parameters": [
          {
            "name": "name",
            "type": "string"
          }
        ],
        "returns": "void",
        "description": "Re-queues a failed file and restarts the upload — the File object is still held in memory."
      },
      {
        "name": "removeFile",
        "parameters": [
          {
            "name": "name",
            "type": "string"
          }
        ],
        "returns": "void",
        "description": "Removes a file from the list, or dismisses a rejected row. Aborts the upload if it is in flight."
      }
    ],
    "events": [
      {
        "name": "ed-upload-change",
        "react": "onEdUploadChange",
        "type": "{ files: UploadFileItem[] }",
        "description": "Emitted when the set of files changes (added or removed)."
      },
      {
        "name": "ed-upload-progress",
        "react": "onEdUploadProgress",
        "type": "{ name: string, loaded: number, total: number, percent: number }",
        "description": "Emitted while a file uploads."
      },
      {
        "name": "ed-upload-finished",
        "react": "onEdUploadFinished",
        "type": "{ files: UploadedFile[] }",
        "description": "Emitted once all queued uploads have settled."
      },
      {
        "name": "ed-upload-error",
        "react": "onEdUploadError",
        "type": "{ name: string, reason: UploadErrorReason }",
        "description": "Emitted on a validation rejection or a failed upload."
      },
      {
        "name": "ed-file-preview",
        "react": "onEdFilePreview",
        "type": "{ name: string }",
        "description": "Emitted when a file's preview action is activated (requires `viewable`)."
      }
    ],
    "slots": [],
    "cssProperties": [
      {
        "name": "--ed-upload-illustration-size",
        "default": "4rem",
        "description": "Size of the drag & drop illustration icon. Raise it when the dropzone fills a large area (e.g. a full-screen scan dialog)."
      }
    ],
    "parts": [
      {
        "name": "base",
        "description": "The component wrapper."
      },
      {
        "name": "dropzone",
        "description": "The drag & drop area."
      },
      {
        "name": "summary",
        "description": "The \"N files · size\" summary (multi mode)."
      },
      {
        "name": "list",
        "description": "The file list (multi mode)."
      },
      {
        "name": "file",
        "description": "A single file row."
      },
      {
        "name": "file-name",
        "description": "A file row's name."
      },
      {
        "name": "file-size",
        "description": "A file row's size."
      },
      {
        "name": "file-actions",
        "description": "A file row's action buttons."
      },
      {
        "name": "file-status",
        "description": "A file row's status cell (progress bar or status icon)."
      },
      {
        "name": "file-reason",
        "description": "A rejected row's reason text."
      }
    ],
    "states": []
  },
  "import": "import '@eurodata/eurodata-ui/dist/components/upload/upload.js';",
  "react": {
    "component": "EdUpload",
    "import": "import EdUpload from '@eurodata/eurodata-ui/dist/react/upload/index.js';"
  }
}