hakumi_components 0.1.17.pre → 0.1.19.pre

data/app/javascript/hakumi_components/controllers/hakumi/upload_controller.js

@@ -5,6 +5,78 @@ const ALLOWED_URL_PROTOCOLS = ["http:", "https:", "data:"]
 
 
 const VALID_STATUSES = ["ready", "uploading", "done", "error", "aborted"]
+const BLOCKED_UPLOAD_HEADERS = ["cookie", "host", "origin", "referer"]
+const IMAGE_DATA_URL_PREFIX = "data:image/"
+const MAX_IMAGE_DATA_URL_LENGTH = 1024 * 100
+
+const generateUploadUid = () => `upload_${Date.now()}_${Math.random().toString(16).slice(2)}`
+
+const sanitizeUploadFileName = (name) => {
+  if (typeof name !== "string") return "file"
+
+  return name
+    .replace(/[<>:"\/\\|?*\x00-\x1f]/g, "_")
+    .slice(0, 255)
+}
+
+const sanitizeUploadUrl = (url) => {
+  if (!url || typeof url !== "string") return null
+
+  try {
+    if (url.startsWith("data:")) {
+      if (url.startsWith(IMAGE_DATA_URL_PREFIX)) {
+        return url.slice(0, MAX_IMAGE_DATA_URL_LENGTH)
+      }
+      return null
+    }
+
+    const parsed = new URL(url)
+    if (ALLOWED_URL_PROTOCOLS.includes(parsed.protocol)) {
+      return parsed.href
+    }
+  } catch {
+  }
+
+  return null
+}
+
+const normalizeUploadStatus = (status) => {
+  if (typeof status !== "string") return null
+  const normalized = status.toLowerCase()
+  return VALID_STATUSES.includes(normalized) ? normalized : null
+}
+
+const clampUploadPercent = (percent) => {
+  const num = Number(percent)
+  if (isNaN(num)) return 0
+  return Math.max(0, Math.min(100, Math.round(num)))
+}
+
+const isBlockedUploadHeader = (header) => BLOCKED_UPLOAD_HEADERS.includes(header.toLowerCase())
+
+const normalizeAcceptTypes = (accept) => accept.split(",").map((type) => type.trim().toLowerCase())
+
+const normalizeFileTypeMatchInput = (file) => ({
+  name: file.name.toLowerCase(),
+  type: file.type.toLowerCase()
+})
+
+const isPreviewRecord = (record) => record.status === "done" && record.url
+
+const clearUploadXhr = (record, xhr) => {
+  if (record.xhr === xhr) delete record.xhr
+}
+
+const releaseUploadRecordResources = (record) => {
+  if (record.xhr) record.xhr.abort()
+  if (record.blobUrl && record.url) URL.revokeObjectURL(record.url)
+}
+
+const normalizePreviewItem = (record) => ({
+  src: record.url,
+  alt: record.name,
+  uid: record.uid
+})
 
 export default class extends RegistryController {
   static targets = ["input", "list", "dropzone", "inlineTrigger", "avatar", "avatarWrapper"]
@@ -28,11 +100,18 @@ export default class extends RegistryController {
     inlineTrigger: { type: Boolean, default: false },
     avatarShape: String,
     avatarSize: Number,
-    avatarIcon: String
+    avatarIcon: String,
+    // i18n
+    previewLabel: { type: String, default: "Preview" },
+    removeLabel: { type: String, default: "Remove" },
+    closeLabel: { type: String, default: "Close" },
+    previousLabel: { type: String, default: "Previous" },
+    nextLabel: { type: String, default: "Next" }
   }
 
   
   setup() {
+    this.activeAvatarUploadRecord = null
     this.fileList = this.normalizeFileList(this.defaultFileListValue || [])
     this.renderFileList()
   }
@@ -40,14 +119,10 @@ export default class extends RegistryController {
   
   teardown() {
 
-    this.fileList.forEach((record) => {
-      if (record.xhr) {
-        record.xhr.abort()
-      }
-      if (record.blobUrl && record.url) {
-        URL.revokeObjectURL(record.url)
-      }
-    })
+    this.#closePreviewModal({ animate: false })
+
+    this.releaseActiveAvatarUploadRecord()
+    this.fileList.forEach(releaseUploadRecordResources)
   }
 
   
@@ -91,15 +166,7 @@ export default class extends RegistryController {
   addFile(fileData) {
     if (!fileData || typeof fileData !== "object") return null
 
-    const record = {
-      uid: `upload_${Date.now()}_${Math.random().toString(16).slice(2)}`,
-      name: this.sanitizeFileName(fileData.name || "file"),
-      status: this.validateStatus(fileData.status) || "ready",
-      url: this.sanitizeUrl(fileData.url),
-      percent: this.clampPercent(fileData.percent || 0),
-      size: typeof fileData.size === "number" ? fileData.size : null,
-      error: typeof fileData.error === "string" ? fileData.error : null
-    }
+    const record = this.normalizeApiFileData(fileData)
 
 
     if (this.hasMaxCountValue && this.fileList.length >= this.maxCountValue) {
@@ -205,54 +272,40 @@ export default class extends RegistryController {
 
   
 
-  sanitizeFileName(name) {
-    if (typeof name !== "string") return "file"
-
-    return name
-      .replace(/[<>:"\/\\|?*\x00-\x1f]/g, "_")
-      .slice(0, 255)
+  normalizeApiFileData(fileData) {
+    return {
+      uid: generateUploadUid(),
+      name: this.sanitizeFileName(fileData.name || "file"),
+      status: this.validateStatus(fileData.status) || "ready",
+      url: this.sanitizeUrl(fileData.url),
+      percent: this.clampPercent(fileData.percent || 0),
+      size: typeof fileData.size === "number" ? fileData.size : null,
+      error: typeof fileData.error === "string" ? fileData.error : null
+    }
   }
 
   
 
-  sanitizeUrl(url) {
-    if (!url || typeof url !== "string") return null
-
-    try {
+  sanitizeFileName(name) {
+    return sanitizeUploadFileName(name)
+  }
 
-      if (url.startsWith("data:")) {
 
-        if (url.startsWith("data:image/")) {
-          return url.slice(0, 1024 * 100)
-        }
-        return null
-      }
 
-      const parsed = new URL(url)
-      if (ALLOWED_URL_PROTOCOLS.includes(parsed.protocol)) {
-        return parsed.href
-      }
-    } catch {
-
-    }
-
-    return null
+  sanitizeUrl(url) {
+    return sanitizeUploadUrl(url)
   }
 
   
 
   validateStatus(status) {
-    if (typeof status !== "string") return null
-    const normalized = status.toLowerCase()
-    return VALID_STATUSES.includes(normalized) ? normalized : null
+    return normalizeUploadStatus(status)
   }
 
   
 
   clampPercent(percent) {
-    const num = Number(percent)
-    if (isNaN(num)) return 0
-    return Math.max(0, Math.min(100, Math.round(num)))
+    return clampUploadPercent(percent)
   }
 
   
@@ -260,21 +313,32 @@ export default class extends RegistryController {
   validateFileType(file) {
     if (!this.acceptValue) return true
 
-    const acceptTypes = this.acceptValue.split(",").map((t) => t.trim().toLowerCase())
-    const fileName = file.name.toLowerCase()
-    const fileType = file.type.toLowerCase()
+    const acceptTypes = normalizeAcceptTypes(this.acceptValue)
+    const fileMatch = normalizeFileTypeMatchInput(file)
 
     return acceptTypes.some((accept) => {
       if (accept.startsWith(".")) {
-        return fileName.endsWith(accept)
+        return fileMatch.name.endsWith(accept)
       } else if (accept.endsWith("/*")) {
-        return fileType.startsWith(accept.slice(0, -2))
+        return fileMatch.type.startsWith(accept.slice(0, -2))
       } else {
-        return fileType === accept
+        return fileMatch.type === accept
       }
     })
   }
 
+  validationErrorForFile(file, { avatar = false } = {}) {
+    if (!this.validateFileType(file)) {
+      return avatar ? "Please upload an image file" : "File type not accepted"
+    }
+
+    if (this.hasMaxSizeValue && file.size > this.maxSizeValue) {
+      return "File exceeds max size"
+    }
+
+    return null
+  }
+
   getCsrfToken() {
     const meta = document.querySelector('meta[name="csrf-token"]')
     return meta ? meta.getAttribute("content") : null
@@ -335,20 +399,11 @@ export default class extends RegistryController {
 
     acceptedFiles.forEach((file) => {
       const record = this.buildFileRecord(file)
+      const validationError = this.validationErrorForFile(file)
 
-
-      if (!this.validateFileType(file)) {
-        record.status = "error"
-        record.error = "File type not accepted"
-        this.fileList.push(record)
-        this.dispatchError(record)
-        return
-      }
-
-
-      if (this.hasMaxSizeValue && file.size > this.maxSizeValue) {
+      if (validationError) {
         record.status = "error"
-        record.error = "File exceeds max size"
+        record.error = validationError
         this.fileList.push(record)
         this.dispatchError(record)
       } else {
@@ -388,14 +443,7 @@ export default class extends RegistryController {
     if (!record) return
 
 
-    if (record.xhr) {
-      record.xhr.abort()
-    }
-
-
-    if (record.blobUrl && record.url) {
-      URL.revokeObjectURL(record.url)
-    }
+    releaseUploadRecordResources(record)
 
     this.fileList = this.fileList.filter((item) => item.uid !== record.uid)
     this.renderFileList()
@@ -414,10 +462,7 @@ export default class extends RegistryController {
 
   removeAll() {
 
-    this.fileList.forEach((record) => {
-      if (record.xhr) record.xhr.abort()
-      if (record.blobUrl && record.url) URL.revokeObjectURL(record.url)
-    })
+    this.fileList.forEach(releaseUploadRecordResources)
 
     this.fileList = []
     this.renderFileList()
@@ -431,10 +476,7 @@ export default class extends RegistryController {
 
   setFileList(list) {
 
-    this.fileList.forEach((record) => {
-      if (record.xhr) record.xhr.abort()
-      if (record.blobUrl && record.url) URL.revokeObjectURL(record.url)
-    })
+    this.fileList.forEach(releaseUploadRecordResources)
 
     this.fileList = this.normalizeFileList(list || [])
     this.renderFileList()
@@ -444,7 +486,9 @@ export default class extends RegistryController {
   abort(file) {
     const record = this.resolveRecord(file)
     if (!record || !record.xhr) return
-    record.xhr.abort()
+    const { xhr } = record
+    xhr.abort()
+    clearUploadXhr(record, xhr)
     record.status = "aborted"
     this.renderFileList()
     this.dispatchError(record, "aborted")
@@ -453,7 +497,11 @@ export default class extends RegistryController {
 
   abortAll() {
     this.fileList.forEach((record) => {
-      if (record.xhr) record.xhr.abort()
+      if (record.xhr) {
+        const { xhr } = record
+        xhr.abort()
+        clearUploadXhr(record, xhr)
+      }
       if (record.status === "uploading") record.status = "aborted"
     })
     this.renderFileList()
@@ -480,9 +528,7 @@ export default class extends RegistryController {
     record.xhr = xhr
 
 
-    if (this.withCredentialsValue) {
-      xhr.withCredentials = true
-    }
+    this.applyUploadRequestOptions(xhr)
 
     xhr.upload.addEventListener("progress", (event) => {
       if (!event.lengthComputable) return
@@ -492,6 +538,8 @@ export default class extends RegistryController {
     })
 
     xhr.addEventListener("load", () => {
+      clearUploadXhr(record, xhr)
+
       if (xhr.status >= 200 && xhr.status < 300) {
         record.status = "done"
         record.percent = 100
@@ -513,6 +561,7 @@ export default class extends RegistryController {
     })
 
     xhr.addEventListener("error", () => {
+      clearUploadXhr(record, xhr)
       record.status = "error"
       record.error = "Network error"
       this.renderFileList()
@@ -521,32 +570,43 @@ export default class extends RegistryController {
     })
 
     xhr.addEventListener("abort", () => {
+      clearUploadXhr(record, xhr)
       record.status = "aborted"
       this.renderFileList()
       this.dispatchError(record, "aborted")
       this.dispatchChange(record)
     })
 
-    xhr.open("POST", this.actionValue)
+    this.sendUploadRequest(xhr, record.raw)
+  }
 
+  applyUploadRequestOptions(xhr) {
+    if (this.withCredentialsValue) {
+      xhr.withCredentials = true
+    }
+  }
+
+  openUploadRequest(xhr) {
+    xhr.open("POST", this.actionValue)
 
     const csrfToken = this.getCsrfToken()
     if (csrfToken) {
       xhr.setRequestHeader("X-CSRF-Token", csrfToken)
     }
 
-
     const headers = this.ensureObject(this.headersValue)
     if (headers) {
-      Object.entries(headers).forEach(([key, value]) => {
-
-        const lowerKey = key.toLowerCase()
-        if (!["cookie", "host", "origin", "referer"].includes(lowerKey)) {
-          xhr.setRequestHeader(key, value)
-        }
+      this.getSafeUploadHeaders(headers).forEach(([key, value]) => {
+        xhr.setRequestHeader(key, value)
       })
     }
+  }
+
+  getSafeUploadHeaders(headers) {
+    return Object.entries(headers).filter(([key]) => !isBlockedUploadHeader(key))
+  }
 
+  buildUploadFormData(file) {
     const formData = new FormData()
     const extraData = this.ensureObject(this.dataValue)
     if (extraData) {
@@ -555,33 +615,38 @@ export default class extends RegistryController {
       })
     }
 
-    formData.append(this.nameValue || "file", record.raw)
-    xhr.send(formData)
+    formData.append(this.nameValue || "file", file)
+    return formData
+  }
+
+  sendUploadRequest(xhr, file) {
+    this.openUploadRequest(xhr)
+    xhr.send(this.buildUploadFormData(file))
   }
 
   normalizeFileList(list) {
-    return (list || []).map((item, index) => {
-      if (item instanceof File) return this.buildFileRecord(item)
-
-      const record = {
-        uid: item.uid || `upload_${Date.now()}_${index}`,
-        name: this.sanitizeFileName(item.name || item.filename || "file"),
-        status: this.validateStatus(item.status) || "ready",
-        url: this.sanitizeUrl(item.url),
-        percent: this.clampPercent(item.percent || 0),
-        size: item.size,
-        response: item.response,
-        error: typeof item.error === "string" ? item.error : null,
-        raw: item.raw || item.file
-      }
+    return (list || []).map((item, index) => this.normalizeFileListItem(item, index))
+  }
 
-      return record
-    })
+  normalizeFileListItem(item, index) {
+    if (item instanceof File) return this.buildFileRecord(item)
+
+    return {
+      uid: item.uid || `upload_${Date.now()}_${index}`,
+      name: this.sanitizeFileName(item.name || item.filename || "file"),
+      status: this.validateStatus(item.status) || "ready",
+      url: this.sanitizeUrl(item.url),
+      percent: this.clampPercent(item.percent || 0),
+      size: item.size,
+      response: item.response,
+      error: typeof item.error === "string" ? item.error : null,
+      raw: item.raw || item.file
+    }
   }
 
   buildFileRecord(file) {
     const record = {
-      uid: `upload_${Date.now()}_${Math.random().toString(16).slice(2)}`,
+      uid: generateUploadUid(),
       name: this.sanitizeFileName(file.name),
       status: "ready",
       percent: 0,
@@ -675,7 +740,7 @@ export default class extends RegistryController {
           viewButton.type = "button"
           viewButton.className = "hakumi-upload-list-item-action hakumi-upload-list-item-view"
           viewButton.innerHTML = `<svg viewBox="64 64 896 896" width="1em" height="1em" fill="currentColor"><path d="M942.2 486.2C847.4 286.5 704.1 186 512 186c-192.2 0-335.4 100.5-430.2 300.3a60.3 60.3 0 000 51.5C176.6 737.5 319.9 838 512 838c192.2 0 335.4-100.5 430.2-300.3 7.7-16.2 7.7-35 0-51.5zM512 766c-161.3 0-279.4-81.8-362.7-254C232.6 339.8 350.7 258 512 258c161.3 0 279.4 81.8 362.7 254C791.5 684.2 673.4 766 512 766zm-4-430c-97.2 0-176 78.8-176 176s78.8 176 176 176 176-78.8 176-176-78.8-176-176-176zm0 288c-61.9 0-112-50.1-112-112s50.1-112 112-112 112 50.1 112 112-50.1 112-112 112z"/></svg>`
-          viewButton.title = "Preview"
+          viewButton.title = this.previewLabelValue
           viewButton.addEventListener("click", (e) => {
             e.stopPropagation()
             this.openPreview(record)
@@ -687,7 +752,7 @@ export default class extends RegistryController {
         removeButton.type = "button"
         removeButton.className = "hakumi-upload-list-item-action hakumi-upload-list-item-remove"
         removeButton.innerHTML = `<svg viewBox="64 64 896 896" width="1em" height="1em" fill="currentColor"><path d="M360 184h-8c4.4 0 8-3.6 8-8v8h304v-8c0 4.4 3.6 8 8 8h-8v72h72v-80c0-35.3-28.7-64-64-64H352c-35.3 0-64 28.7-64 64v80h72v-72zm504 72H160c-17.7 0-32 14.3-32 32v32c0 4.4 3.6 8 8 8h60.4l24.7 523c1.6 34.1 29.8 61 63.9 61h454c34.2 0 62.3-26.8 63.9-61l24.7-523H888c4.4 0 8-3.6 8-8v-32c0-17.7-14.3-32-32-32zM731.3 840H292.7l-24.2-512h487l-24.2 512z"/></svg>`
-        removeButton.title = "Remove"
+        removeButton.title = this.removeLabelValue
         removeButton.addEventListener("click", (e) => {
           e.stopPropagation()
           this.remove(record.uid)
@@ -702,7 +767,7 @@ export default class extends RegistryController {
         removeButton.type = "button"
         removeButton.className = "hakumi-upload-list-item-action hakumi-upload-list-item-remove"
         removeButton.textContent = "×"
-        removeButton.title = "Remove"
+        removeButton.title = this.removeLabelValue
         removeButton.addEventListener("click", (e) => {
           e.stopPropagation()
           this.remove(record.uid)
@@ -808,42 +873,21 @@ export default class extends RegistryController {
   handleAvatarUpload(file) {
     if (!this.hasAvatarTarget || !this.hasAvatarWrapperTarget) return
 
-
-    if (!this.validateFileType(file)) {
-      if (window.HakumiComponents?.renderComponent) {
-        window.HakumiComponents.renderComponent("message", {
-          params: {
-            id: "hakumi-upload-avatar-message",
-            type: "error",
-            message: "Please upload an image file",
-            duration: 3
-          }
-        })
-      }
+    const validationError = this.validationErrorForFile(file, { avatar: true })
+    if (validationError) {
+      const record = this.buildAvatarErrorRecord(file, validationError)
+      this.dispatchError(record, record.error)
       return
     }
 
-
-    if (this.hasMaxSizeValue && file.size > this.maxSizeValue) {
-      if (window.HakumiComponents?.renderComponent) {
-        window.HakumiComponents.renderComponent("message", {
-          params: {
-            id: "hakumi-upload-avatar-message",
-            type: "error",
-            message: "File exceeds max size",
-            duration: 3
-          }
-        })
-      }
-      return
+    const previousAvatarState = this.captureAvatarState()
+    const previousAvatarRecord = this.activeAvatarUploadRecord
+    const releasePreviousAvatarOnSuccess = previousAvatarRecord?.status === "done"
+    if (!releasePreviousAvatarOnSuccess) {
+      this.releaseActiveAvatarUploadRecord(previousAvatarRecord)
     }
 
-
-    this.avatarWrapperTarget.classList.add("hakumi-upload-avatar-wrapper-loading")
-
-
-    const loadingIcon = `<span class="anticon anticon-loading" style="animation: spin 1s linear infinite;"><svg viewBox="0 0 1024 1024" width="1em" height="1em" fill="currentColor"><path d="M988 548c-19.9 0-36-16.1-36-36 0-59.4-11.6-117-34.6-171.3a440.45 440.45 0 00-94.3-139.9 437.71 437.71 0 00-139.9-94.3C629 83.6 571.4 72 512 72c-19.9 0-36-16.1-36-36s16.1-36 36-36c69.1 0 136.2 13.5 199.3 40.3C772.3 66 827 103 874 150c47 47 83.9 101.8 109.7 162.7 26.7 63.1 40.2 130.2 40.2 199.3.1 19.9-16 36-35.9 36z"></path></svg></span>`
-    this.avatarTarget.innerHTML = loadingIcon
+    this.showAvatarLoading()
 
 
     const previewUrl = URL.createObjectURL(file)
@@ -852,11 +896,19 @@ export default class extends RegistryController {
     const record = this.buildFileRecord(file)
     record.url = previewUrl
     record.blobUrl = true
+    this.activeAvatarUploadRecord = record
 
 
     const isDemoMode = !this.actionValue || this.actionValue === "#"
 
     const updateAvatar = () => {
+      if (this.activeAvatarUploadRecord !== record) return
+
+      if (releasePreviousAvatarOnSuccess) {
+        releaseUploadRecordResources(previousAvatarRecord)
+      }
+      record.status = "done"
+      record.percent = 100
       this.avatarWrapperTarget.classList.remove("hakumi-upload-avatar-wrapper-loading")
 
 
@@ -877,20 +929,28 @@ export default class extends RegistryController {
       setTimeout(updateAvatar, 1500)
     } else {
 
-      this.performAvatarUpload(record, updateAvatar)
+      this.performAvatarUpload(record, updateAvatar, () => {
+        this.restoreFailedAvatarUpload(record, previousAvatarState, previousAvatarRecord)
+      })
     }
   }
 
+  showAvatarLoading() {
+    this.avatarWrapperTarget.classList.add("hakumi-upload-avatar-wrapper-loading")
+    const loadingIcon = `<span class="anticon anticon-loading" style="animation: spin 1s linear infinite;"><svg viewBox="0 0 1024 1024" width="1em" height="1em" fill="currentColor"><path d="M988 548c-19.9 0-36-16.1-36-36 0-59.4-11.6-117-34.6-171.3a440.45 440.45 0 00-94.3-139.9 437.71 437.71 0 00-139.9-94.3C629 83.6 571.4 72 512 72c-19.9 0-36-16.1-36-36s16.1-36 36-36c69.1 0 136.2 13.5 199.3 40.3C772.3 66 827 103 874 150c47 47 83.9 101.8 109.7 162.7 26.7 63.1 40.2 130.2 40.2 199.3.1 19.9-16 36-35.9 36z"></path></svg></span>`
+    this.avatarTarget.innerHTML = loadingIcon
+  }
+
   
 
-  performAvatarUpload(record, onSuccess) {
+  performAvatarUpload(record, onSuccess, onError = () => this.clearAvatarErrorState()) {
     const xhr = new XMLHttpRequest()
+    record.xhr = xhr
 
-    if (this.withCredentialsValue) {
-      xhr.withCredentials = true
-    }
+    this.applyUploadRequestOptions(xhr)
 
     xhr.addEventListener("load", () => {
+      clearUploadXhr(record, xhr)
       if (xhr.status >= 200 && xhr.status < 300) {
         try {
           record.response = JSON.parse(xhr.response)
@@ -899,43 +959,67 @@ export default class extends RegistryController {
         }
         onSuccess()
       } else {
-        this.avatarWrapperTarget?.classList.remove("hakumi-upload-avatar-wrapper-loading")
+        onError()
+        record.status = "error"
+        record.error = xhr.statusText || "Upload failed"
         this.dispatchError(record, xhr.statusText || "Upload failed")
       }
     })
 
     xhr.addEventListener("error", () => {
-      this.avatarWrapperTarget?.classList.remove("hakumi-upload-avatar-wrapper-loading")
+      clearUploadXhr(record, xhr)
+      onError()
+      record.status = "error"
+      record.error = "Network error"
       this.dispatchError(record, "Network error")
     })
 
-    xhr.open("POST", this.actionValue)
+    this.sendUploadRequest(xhr, record.raw)
+  }
 
-    const csrfToken = this.getCsrfToken()
-    if (csrfToken) {
-      xhr.setRequestHeader("X-CSRF-Token", csrfToken)
-    }
+  buildAvatarErrorRecord(file, error) {
+    const record = this.buildFileRecord(file)
+    record.status = "error"
+    record.error = error
+    return record
+  }
 
-    const headers = this.ensureObject(this.headersValue)
-    if (headers) {
-      Object.entries(headers).forEach(([key, value]) => {
-        const lowerKey = key.toLowerCase()
-        if (!["cookie", "host", "origin", "referer"].includes(lowerKey)) {
-          xhr.setRequestHeader(key, value)
-        }
-      })
+  captureAvatarState() {
+    if (!this.hasAvatarTarget) return { html: "", image: false }
+
+    return {
+      html: this.avatarTarget.innerHTML,
+      image: this.avatarTarget.classList.contains("hakumi-avatar-image")
     }
+  }
 
-    const formData = new FormData()
-    const extraData = this.ensureObject(this.dataValue)
-    if (extraData) {
-      Object.entries(extraData).forEach(([key, value]) => {
-        formData.append(key, value)
-      })
+  restoreAvatarState(state) {
+    this.avatarWrapperTarget?.classList.remove("hakumi-upload-avatar-wrapper-loading")
+    if (!this.hasAvatarTarget) return
+
+    this.avatarTarget.innerHTML = state?.html || ""
+    this.avatarTarget.classList.toggle("hakumi-avatar-image", Boolean(state?.image))
+  }
+
+  restoreFailedAvatarUpload(record, previousAvatarState, previousAvatarRecord = null) {
+    this.restoreAvatarState(previousAvatarState)
+    this.releaseActiveAvatarUploadRecord(record)
+    if (previousAvatarRecord?.status === "done") {
+      this.activeAvatarUploadRecord = previousAvatarRecord
     }
+  }
 
-    formData.append(this.nameValue || "file", record.raw)
-    xhr.send(formData)
+  clearAvatarErrorState() {
+    this.restoreAvatarState({ html: "", image: false })
+  }
+
+  releaseActiveAvatarUploadRecord(record = this.activeAvatarUploadRecord) {
+    if (!record) return
+
+    releaseUploadRecordResources(record)
+    if (this.activeAvatarUploadRecord === record) {
+      this.activeAvatarUploadRecord = null
+    }
   }
 
 
@@ -946,12 +1030,8 @@ export default class extends RegistryController {
 
   getPreviewItems() {
     return this.fileList
-      .filter((record) => record.status === "done" && record.url)
-      .map((record) => ({
-        src: record.url,
-        alt: record.name,
-        uid: record.uid
-      }))
+      .filter(isPreviewRecord)
+      .map(normalizePreviewItem)
   }
 
   
@@ -971,17 +1051,30 @@ export default class extends RegistryController {
   #previewState = {
     modal: null,
     items: [],
-    currentIndex: 0
+    currentIndex: 0,
+    closeTimer: null
   }
 
   #createPreviewModal(items, startIndex) {
 
-    this.#closePreviewModal()
+    this.#closePreviewModal({ animate: false })
+    this.#setPreviewItems(items, startIndex)
+
+    const modal = this.#buildPreviewModal()
 
+    this.#mountPreviewModal(modal)
+    this.#bindPreviewModalControls(modal)
+    this.#bindPreviewKeyboardNavigation()
+    this.#activatePreviewModal(modal)
+  }
+
+  #setPreviewItems(items, startIndex) {
     this.#previewState.items = items
     this.#previewState.currentIndex = startIndex
+  }
 
-
+  #buildPreviewModal() {
+    const { items, currentIndex } = this.#previewState
     const modal = document.createElement("div")
     modal.className = "hakumi-upload-preview-root"
     modal.innerHTML = `
@@ -991,19 +1084,19 @@ export default class extends RegistryController {
           <img class="hakumi-upload-preview-img" src="" alt="" />
         </div>
         <div class="hakumi-upload-preview-operations">
-          <button type="button" class="hakumi-upload-preview-close" title="Close">
+          <button type="button" class="hakumi-upload-preview-close" title="${this.closeLabelValue}">
             <svg viewBox="64 64 896 896" width="1em" height="1em" fill="currentColor"><path d="M563.8 512l262.5-312.9c4.4-5.2.7-13.1-6.1-13.1h-79.8c-4.7 0-9.2 2.1-12.3 5.7L511.6 449.8 295.1 191.7c-3-3.6-7.5-5.7-12.3-5.7H203c-6.8 0-10.5 7.9-6.1 13.1L459.4 512 196.9 824.9A7.95 7.95 0 00203 838h79.8c4.7 0 9.2-2.1 12.3-5.7l216.5-258.1 216.5 258.1c3 3.6 7.5 5.7 12.3 5.7h79.8c6.8 0 10.5-7.9 6.1-13.1L563.8 512z"/></svg>
           </button>
         </div>
         ${items.length > 1 ? `
-          <button type="button" class="hakumi-upload-preview-switch hakumi-upload-preview-switch-left" title="Previous">
+          <button type="button" class="hakumi-upload-preview-switch hakumi-upload-preview-switch-left" title="${this.previousLabelValue}">
             <svg viewBox="64 64 896 896" width="1em" height="1em" fill="currentColor"><path d="M724 218.3V141c0-6.7-7.7-10.4-12.9-6.3L260.3 486.8a31.86 31.86 0 000 50.3l450.8 352.1c5.3 4.1 12.9.4 12.9-6.3v-77.3c0-4.9-2.3-9.6-6.1-12.6l-360-281 360-281.1c3.8-3 6.1-7.7 6.1-12.6z"/></svg>
           </button>
-          <button type="button" class="hakumi-upload-preview-switch hakumi-upload-preview-switch-right" title="Next">
+          <button type="button" class="hakumi-upload-preview-switch hakumi-upload-preview-switch-right" title="${this.nextLabelValue}">
             <svg viewBox="64 64 896 896" width="1em" height="1em" fill="currentColor"><path d="M765.7 486.8L314.9 134.7A7.97 7.97 0 00302 141v77.3c0 4.9 2.3 9.6 6.1 12.6l360 281.1-360 281.1c-3.9 3-6.1 7.7-6.1 12.6V183c0 6.7 7.7 10.4 12.9 6.3l450.8-352.1a31.96 31.96 0 000-50.4z"/></svg>
           </button>
           <div class="hakumi-upload-preview-counter">
-            <span class="hakumi-upload-preview-counter-current">${startIndex + 1}</span>
+            <span class="hakumi-upload-preview-counter-current">${currentIndex + 1}</span>
             <span>/</span>
             <span class="hakumi-upload-preview-counter-total">${items.length}</span>
           </div>
@@ -1011,28 +1104,33 @@ export default class extends RegistryController {
       </div>
     `
 
+    return modal
+  }
+
+  #mountPreviewModal(modal) {
     this.#previewState.modal = modal
     document.body.appendChild(modal)
     document.body.style.overflow = "hidden"
-
-
     this.#updatePreviewImage()
+  }
 
-
+  #bindPreviewModalControls(modal) {
     modal.querySelector(".hakumi-upload-preview-mask").addEventListener("click", () => this.#closePreviewModal())
     modal.querySelector(".hakumi-upload-preview-close").addEventListener("click", () => this.#closePreviewModal())
     modal.querySelector(".hakumi-upload-preview-switch-left")?.addEventListener("click", () => this.#prevPreviewImage())
     modal.querySelector(".hakumi-upload-preview-switch-right")?.addEventListener("click", () => this.#nextPreviewImage())
+  }
 
-
+  #bindPreviewKeyboardNavigation() {
     this._previewKeyHandler = (e) => {
       if (e.key === "Escape") this.#closePreviewModal()
       else if (e.key === "ArrowLeft") this.#prevPreviewImage()
       else if (e.key === "ArrowRight") this.#nextPreviewImage()
     }
     document.addEventListener("keydown", this._previewKeyHandler)
+  }
 
-
+  #activatePreviewModal(modal) {
     requestAnimationFrame(() => {
       modal.classList.add("hakumi-upload-preview-active")
     })
@@ -1067,21 +1165,39 @@ export default class extends RegistryController {
     this.#updatePreviewImage()
   }
 
-  #closePreviewModal() {
+  #closePreviewModal({ animate = true } = {}) {
     const { modal } = this.#previewState
     if (!modal) return
 
     modal.classList.remove("hakumi-upload-preview-active")
+    this.#unbindPreviewKeyboardNavigation()
 
-    if (this._previewKeyHandler) {
-      document.removeEventListener("keydown", this._previewKeyHandler)
-      this._previewKeyHandler = null
-    }
+    if (this.#previewState.closeTimer) clearTimeout(this.#previewState.closeTimer)
 
-    setTimeout(() => {
+    const removeModal = () => {
       modal.remove()
-      this.#previewState.modal = null
-      document.body.style.overflow = ""
-    }, 300)
+      if (this.#previewState.modal === modal) {
+        this.#resetPreviewModalState()
+      }
+    }
+
+    if (animate) {
+      this.#previewState.closeTimer = setTimeout(removeModal, 300)
+    } else {
+      removeModal()
+    }
+  }
+
+  #unbindPreviewKeyboardNavigation() {
+    if (!this._previewKeyHandler) return
+
+    document.removeEventListener("keydown", this._previewKeyHandler)
+    this._previewKeyHandler = null
+  }
+
+  #resetPreviewModalState() {
+    this.#previewState.modal = null
+    this.#previewState.closeTimer = null
+    document.body.style.overflow = ""
   }
 }