# `src/components/upload/Upload.ts`:

## class: `Upload`, `btu-upload`

### Superclass

| Name         | Module | Package |
| ------------ | ------ | ------- |
| `LitElement` |        | lit     |

### Mixins

| Name                | Module                         | Package |
| ------------------- | ------------------------------ | ------- |
| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |

### Fields

| Name                  | Privacy | Type                       | Default     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Inherited From |
| --------------------- | ------- | -------------------------- | ----------- |   | -------------- |
| `accept`              |         | `string`                   | `''`        | Accepted file types, matching the HTML \`\<input accept>\` attribute format.&#xA;Client-side filter only — the browser's file picker uses this as a hint,&#xA;and drag-drop is enforced by this component. Server-side validation is&#xA;still required.&#xA;&#xA;Supported forms (comma-separated, any combination):&#xA;- \`image/\*\` — MIME wildcard (any image)&#xA;- \`application/pdf\` — exact MIME type&#xA;- \`.pdf\`, \`.docx\` — file extension (case-insensitive)&#xA;&#xA;Examples:&#xA;- \`accept="image/\*"\` — any image&#xA;- \`accept="image/\*,application/pdf"\` — images and PDFs&#xA;- \`accept=".jpg,.jpeg,.png,.heic"\` — specific extensions&#xA;- \`accept=""\` (or omitted) — allow all&#xA;&#xA;Note: users can bypass the file picker's filter (most browsers offer an&#xA;"All Files" option), so this attribute is a UX filter, not a security&#xA;boundary. |                |
| `maxFileSize`         |         | `number`                   | `0`         | Maximum file size in bytes. Files exceeding this are rejected. 0 means unlimited.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |                |
| `maxFiles`            |         | `number`                   | `Infinity`  | Maximum number of files allowed. When omitted, uploads are unlimited.&#xA;\`max-files="1"\` enters single-file mode (selecting a new file replaces the existing one).&#xA;\`max-files="0"\` allows zero files. Values above 1 cap the queue at that many files.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
| `disabled`            |         | `boolean`                  | `false`     | Disables all interaction — file selection, drag-and-drop, and action buttons.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |                |
| `noDrag`              |         | `boolean`                  | `false`     | Disables drag-and-drop. File selection via click still works.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |                |
| `_files`              | private | `Map<string, FileState>`   | `new Map()` |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
| `_items`              | private | `Map<string, UploadItem>`  | `new Map()` |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
| `_milestones`         | private | `Map<string, Set<number>>` | `new Map()` |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
| `_dragOver`           | private | `boolean`                  | `false`     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
| `_dragCounter`        | private | `number`                   | `0`         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
| `_inputEl`            | private | `HTMLInputElement \| null` |             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
| `_dropzoneFull`       | private | `boolean`                  |             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
| `_interactionBlocked` | private | `boolean`                  |             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |
| `_showCountPill`      | private | `boolean`                  |             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                |

### Methods

| Name                   | Privacy | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Parameters                                                | Return                 | Inherited From    |
| ---------------------- | ------- |   | --------------------------------------------------------- | ---------------------- | ----------------- |
| `_handleInputChange`   | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `e: Event`                                                | `void`                 |                   |
| `_handleSelectClick`   | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `e: Event`                                                | `void`                 |                   |
| `_handleDropzoneClick` | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |                                                           | `void`                 |                   |
| `_handleDragEnter`     | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `e: DragEvent`                                            | `void`                 |                   |
| `_handleDragOver`      | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `e: DragEvent`                                            | `void`                 |                   |
| `_handleDragLeave`     | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `e: DragEvent`                                            | `void`                 |                   |
| `_handleDrop`          | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `e: DragEvent`                                            | `void`                 |                   |
| `_processFiles`        | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `files: File[]`                                           | `void`                 |                   |
| `_rejectCount`         | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `file: File`                                              | `void`                 |                   |
| `_validateFile`        | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `file: File`                                              | `boolean`              |                   |
| `_addFile`             | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `file: File`                                              | `void`                 |                   |
| `_reportUnknownId`     | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `method: ApiMethod, id: string`                           | `void`                 |                   |
| `_getOrReport`         | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `method: ApiMethod, id: string`                           | `FileState \| null`    |                   |
| `_renderItem`          | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `fileState: FileState`                                    | `void`                 |                   |
| `setFileProgress`      |         | Update the progress of a file upload.&#xA;Clamps value to 0-100 and coerces non-finite inputs to 0. Announces milestones&#xA;(25%, 50%, 75%) to screen readers; 100% completion is announced by setFileStatus('complete').&#xA;&#xA;Status transitions:&#xA;- \`pending\` → \`uploading\` (auto — first progress report starts the upload)&#xA;- \`uploading\` → \`uploading\` (progress updates)&#xA;- \`error\` → \`error\` (progress updates only; status is preserved so a stale late&#xA;  callback can't wipe the error UI. To recover from error, call&#xA;  \`setFileStatus(id, 'uploading')\` first, then report progress.)&#xA;- \`complete\` → ignored (terminal state) | `id: string, percent: number`                             | `void`                 |                   |
| `setFileStatus`        |         | Set the status of a file.&#xA;Valid statuses: 'uploading', 'complete', 'error'. For 'error' status, an&#xA;optional message can be provided.&#xA;&#xA;Transitions from 'complete' are rejected (terminal state) — a late-resolving&#xA;XHR cannot overwrite a prior success. Rejected calls emit \`btu-upload-api-error\`&#xA;with reason: 'invalid-transition'.                                                                                                                                                                                                                                                                                                                   | `id: string, status: FileStatusSettable, message: string` | `void`                 |                   |
| `setFileSymbol`        |         | Override the icon symbol for a file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `id: string, symbol: string`                              | `void`                 |                   |
| `removeFile`           |         | Remove a file programmatically. Fires \`btu-upload-file-removed\`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `id: string`                                              | `void`                 |                   |
| `getFiles`             |         | Get a snapshot of all current files and their states.&#xA;States are readonly; mutations on the returned array's elements are ineffective.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                           | `readonly FileState[]` |                   |
| `_renderSelectButton`  | private |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `text: string`                                            |                        |                   |
| `emit`                 |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries)                                                                                                                                                                                                                                                                                                                                                                                                 | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>`   | `boolean`              | EventEmitterMixin |

### Events

| Name                        | Type                                                                                                       | Description                                                                                      | Inherited From |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------- |
| `btu-upload-ready`          | `CustomEvent<unknown>`                                                                                     | Fired when the component has completed first render                                              |                |
| `btu-upload-file-added`     | `CustomEvent<{id: string, file: File}>`                                                                    | Fired when a file passes validation and is added                                                 |                |
| `btu-upload-file-removed`   | `CustomEvent<{id: string, file: File}>`                                                                    | Fired when a file is removed (user action, programmatic, or on disconnect for in-flight uploads) |                |
| `btu-upload-file-retry`     | `CustomEvent<{id: string, file: File}>`                                                                    | Fired when user clicks "Try again" on a failed upload                                            |                |
| `btu-upload-file-rejected`  | `CustomEvent<{file: File, reason: 'type' \| 'size' \| 'count'}>`                                           | Fired when a file fails client-side validation or the queue is full                              |                |
| `btu-upload-file-completed` | `CustomEvent<{id: string, file: File}>`                                                                    | Fired when a file's status transitions into 'complete'                                           |                |
| `btu-upload-api-error`      | `CustomEvent<{method: string, id: string, reason: 'unknown-id' \| 'invalid-transition', message: string}>` | Fired when an imperative API call references an unknown id or an illegal status transition       |                |

### Attributes

| Name            | Field       | Inherited From |
| --------------- | ----------- | -------------- |
| `accept`        | accept      |                |
| `max-file-size` | maxFileSize |                |
| `max-files`     | maxFiles    |                |
| `disabled`      | disabled    |                |
| `no-drag`       | noDrag      |                |

### CSS Properties

| Name                                   | Default | Description                                                                                   |
| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `--upload-dropzone-bg`                 |         | Drop zone background color (default: gray-25)                                                 |
| `--upload-dropzone-border-color`       |         | Drop zone border color (default: gray-300; gray-200 when disabled, gray-400 in high-contrast) |
| `--upload-dropzone-border-radius`      |         | Drop zone border radius (default: borderRadius.lg)                                            |
| `--upload-dropzone-hover-bg`           |         | Drop zone hover background (hover default: gray-50; drag-over default: primary-25)            |
| `--upload-dropzone-hover-border-color` |         | Drop zone hover/focus border color (default: primary-300; drag-over uses primary-400)         |
| `--upload-dropzone-focus-ring-color`   |         | Drop zone focus ring color (default: primary-100)                                             |
| `--upload-item-bg`                     |         | Item background color (default: white)                                                        |
| `--upload-item-border-color`           |         | Item border color (default: gray-200)                                                         |
| `--upload-item-active-border-color`    |         | Item active/in-progress border (default: gray-300)                                            |
| `--upload-item-complete-border-color`  |         | Item completed border color (default: primary-500)                                            |
| `--upload-item-error-bg`               |         | Item error background (default: error-25)                                                     |
| `--upload-item-error-border-color`     |         | Item error border color (default: error-300)                                                  |

<hr/>

## Exports

| Kind                        | Name                 | Declaration        | Module                          | Package |
| --------------------------- | -------------------- | ------------------ | ------------------------------- | ------- |
| `js`                        | `FileState`          | FileState          | src/components/upload/Upload.ts |         |
| `js`                        | `FileStatus`         | FileStatus         | src/components/upload/Upload.ts |         |
| `js`                        | `FileStatusSettable` | FileStatusSettable | src/components/upload/Upload.ts |         |
| `js`                        | `default`            | Upload             | src/components/upload/Upload.ts |         |
| `custom-element-definition` | `btu-upload`         | Upload             | src/components/upload/Upload.ts |         |
