@xsolla/xui-uploader 0.174.3 → 0.175.0

package/README.md

@@ -1,6 +1,74 @@
 # Uploader
 
 A cross-platform React file uploader component that provides a button to select files, displays selected files, and allows removing them.
+<!-- BEGIN:xui-mcp-instructions:uploader -->
+A compact button-style control that triggers a file selection dialog and optionally displays a list of uploaded or selected files below the trigger. Supports five sizes, six states including an upload-in-progress loading state, and a toggleable file list. Used wherever a user must attach, replace, or upload a file — profile photos, document uploads, asset imports.
+
+### When to use
+- When the user must select and upload a file from their device — profile picture, document, CSV import, media asset
+- When the file selection happens inline in a form alongside other fields
+- When the number of accepted files is small (one or a few) and a full drag-and-drop zone would occupy too much space
+- When the upload state and error feedback must be communicated within the field itself, without a separate Toast or modal
+
+### When not to use
+
+When batch uploading many files at once with drag-and-drop is the primary interaction — use a dedicated Drag&dropUploader component
+
+When the upload triggers a complex multi-step flow — open a dedicated upload modal instead
+
+When only a URL or link is needed, not an actual file — use a standard Input
+
+### Content guidelines
+
+Trigger label — use a short imperative phrase: *"Upload file"*, *"Choose file"*, *"Add document"*, *"Upload photo"*. For replace scenarios, switch to *"Replace file"* or *"Change photo"*.
+
+Loading label — show *"Uploading…"* or *"Processing…"* while in State=Loading. If the upload has measurable progress, include the percentage: *"Uploading… 64%"*.
+Error messages — be specific and actionable:
+- *"File type not supported. Please upload a PDF or DOCX file."*
+- *"File is too large. Maximum allowed size is 10 MB."*
+- *"Upload failed. Check your connection and try again."*
+- *"Please upload a file to continue."* (required field, empty on submit)
+- File type guidance — add helper text below the component (outside FileUploader) specifying accepted formats and size limits: *"Accepted formats: PDF, DOCX. Max size: 10 MB."* Do not put this information inside the trigger label.
+- Field label — always provide a visible label above the component: *"Profile photo"*, *"Company logo"*, *"Import file"*. Do not rely on the trigger label alone.
+
+Behaviour guidelines (from industry practice)
+
+Click to select — clicking the trigger opens the native OS file selection dialog. After the user selects a file, the component transitions based on the product's flow: either immediately begins uploading (State=Loading) or adds the file to the list (if deferred upload is used).
+
+Loading state — switch to State=Loading immediately when the upload begins. The trigger is non-interactive during upload. Show a progress indicator if the file is large and upload duration is meaningful (e.g. a progress bar inside or below the trigger, outside the component itself).
+
+Upload complete — after a successful upload, return the trigger to State=Default (or a custom *"Replace"* state). If Uploader list=true, add the uploaded file to the list.
+Error handling — switch to State=Error when:
+- The file type is not accepted (e.g. a PNG was uploaded but only PDF is allowed)
+- The file size exceeds the maximum allowed
+- The upload request fails on the server
+- Required file was not provided on form submission Show a specific error message below the trigger.
+- Remove file — clicking the ✕ button in an uploader list item removes that file from the selection. If the product uses immediate upload, also cancel or delete the server-side upload. After removal, if the list is empty, keep Uploader list=true visible (empty state) or revert to Uploader list=false depending on the product logic.
+- Replace file — for single-file contexts, clicking the trigger again while a file is already selected or uploaded should replace the previous selection. Provide a clear label change (e.g. *"Replace file"*) to signal this behaviour.
+- File validation — validate the file type and size client-side before uploading and before switching to State=Loading. Do not start an upload for an invalid file — switch directly to State=Error with a specific message.
+- Disabled state — State=Disable prevents opening the file dialog. Show a tooltip or nearby explanation for why the upload is unavailable.
+- Multiple files — if the product allows multiple file selection, set multiple on the underlying <input type=*"file"*> and enable Uploader list=true to show all selected files. Define a clear max file count and enforce it client-side.
+
+### Accessibility
+
+The trigger must be implemented as a <button> or <label> element associated with a visually hidden <input type=*"file"*>. The <input> must not be the visible trigger.
+
+The trigger must have aria-label if the visible label text is not descriptive enough — e.g. aria-label=*"Upload profile photo"*.
+
+When State=Loading, set aria-busy=*"true"* on the trigger and update aria-label to reflect the in-progress state: aria-label=*"Uploading profile photo…"*.
+
+When State=Error, the error message must be associated via aria-describedby so screen readers announce it when the trigger receives focus.
+
+When State=Disable, the trigger must have aria-disabled=*"true"*. Keep it focusable so screen readers can discover and announce it.
+
+The file list (when Uploader list=true) must be in a region with aria-label=*"Selected files"* or equivalent. Each file item must be announced with its name and size. The remove button for each item must have aria-label=*"Remove [file name]"* — not just aria-label=*"Remove"*.
+
+When a file is removed from the list, announce the removal to screen readers using aria-live=*"polite"*: e.g. *"document.pdf removed"*.
+
+When a file is successfully uploaded or added to the list, use aria-live=*"polite"* to announce: *"document.pdf added"*.
+
+The accepted file types and size limits (shown in helper text) should be linked to the trigger via aria-describedby so screen readers surface the constraints when the trigger is focused.
+<!-- END:xui-mcp-instructions:uploader -->
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-uploader",
-  "version": "0.174.3",
+  "version": "0.175.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -13,10 +13,10 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-button": "0.174.3",
-    "@xsolla/xui-core": "0.174.3",
-    "@xsolla/xui-icons": "0.174.3",
-    "@xsolla/xui-primitives-core": "0.174.3"
+    "@xsolla/xui-button": "0.175.0",
+    "@xsolla/xui-core": "0.175.0",
+    "@xsolla/xui-icons": "0.175.0",
+    "@xsolla/xui-primitives-core": "0.175.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0"