@xsolla/xui-image-uploader 0.174.3 → 0.176.0

package/README.md

@@ -2,6 +2,76 @@
 
 A cross-platform React image uploader component supporting click-to-pick, drag-and-drop (web), controlled and uncontrolled usage, image preview with hover-to-remove, automatic loading state from async `onUpload`, error states, and a wide horizontal layout.
 
+<!-- BEGIN:xui-mcp-instructions:image-uploader -->
+A specialised upload control for images. Renders as a square or landscape rectangle that acts as both the upload trigger and the image preview container. Once an image is uploaded, the zone fills with the image thumbnail; hovering over it reveals controls to replace or remove the image. Supports five sizes, two aspect ratios, and eight states covering the full upload lifecycle.
+
+### When to use
+
+When the user must upload a single image — a profile photo, cover image, product thumbnail, brand logo, avatar, or banner
+- When the uploaded image should be previewed in place immediately after selection
+- When image replacement or removal must be available without navigating away
+- In profile settings, onboarding flows, CMS editors, and product or entity configuration forms
+
+### When not to use
+
+For uploading non-image files (PDFs, CSVs, documents) — use FileUploader or Drag & Drop Uploader
+
+When multiple images must be uploaded simultaneously — use a Drag & Drop Uploader with multiple file support or a dedicated gallery uploader
+
+When the image upload is part of a broader drag-and-drop area — use Drag & Drop Uploader
+
+When cropping or editing the image after selection is required — pair ImageUploader with a dedicated image crop modal triggered after selection
+
+### Content guidelines
+
+Upload hint — inside the zone in Default state, use a short hint below the icon: *"Upload photo"*, *"Add cover image"*, *"Choose image"*. Keep to one line.
+
+Size and format hint — show accepted formats and max size as helper text below the zone (not inside it): *"PNG, JPG, WebP — max 5 MB"*, *"Recommended: 1200 × 630 px"*. At small sizes (S, XS) this may be omitted if space is too tight.
+Error messages — be specific:
+- *"File type not supported. Use JPG, PNG, or WebP."*
+- *"Image exceeds the 5 MB limit."*
+- *"Upload failed. Try again."*
+- *"Please upload a profile photo to continue."* (required field)
+- Replace / Remove labels — use exactly *"Replace"* and *"Remove"* in the overlay. Do not use *"Edit"* for replace or *"Delete"* for remove in this context — the terms are specific to the image slot, not the entity.
+- Field label — always provide a visible label above the component: *"Profile photo"*, *"Cover image"*, *"Company logo"*. Do not rely on the hint inside the zone alone.
+
+- Behaviour guidelines (from industry practice)
+- Click to upload — clicking the zone in Default, Hover, or Focus state opens the native file dialog filtered to image types (e.g. accept=*"image/jpeg,image/png,image/webp,image/gif"*). After the user selects a file, begin validation immediately.
+- File validation — validate client-side before uploading:
+- File type: accept only image formats supported by the product
+- File size: reject files above the maximum (e.g. 5 MB, 10 MB) If validation fails, switch to State=Error with a specific message. Do not start the upload for invalid files.
+- Uploading — after successful validation, transition to State=Uploading and begin the upload. The zone becomes non-interactive.
+- Upload success — on successful upload response, transition to State=Uploaded. The server-returned image URL (or the local object URL) fills the zone as a cropped preview.
+- Upload failure — on network error or server rejection, transition to State=Error with a specific message. The zone becomes interactive again — the user can click to retry.
+- Image fitting — the preview image fills the entire zone using object-fit: cover and object-position: center so the image is always fully visible and cropped to fit, regardless of the original aspect ratio. Do not letterbox or pillarbox.
+- Replace — clicking Replace in State=Uploaded-hover opens the file dialog. The current image stays visible until the new image is successfully uploaded. If the new upload fails, revert to showing the previous image (not the error state) and surface the error as a Toast or inline message.
+- Remove — clicking Remove deletes the image from the selection and returns to State=Default. If the image was already uploaded to a server, also trigger a server-side deletion request. Optionally confirm before removing if the action is irreversible.
+- Touch devices — State=Uploaded-hover is not reachable on touch. Provide always-visible controls below the zone (small icon buttons for Replace and Remove) when the component is used on mobile.
+- Disabled state — the zone cannot be clicked or focused. Provide a tooltip or nearby label explaining why upload is unavailable.
+
+### Accessibility
+
+The upload zone must be implemented as a <button> or a <label> wrapping a hidden <input type=*"file"* accept=*"image/*"*>. It must be keyboard-focusable and activate on Enter / Space.
+
+The zone must have aria-label describing its purpose — e.g. aria-label=*"Upload profile photo"*.
+
+When State=Uploading, set aria-busy=*"true"* on the zone and update aria-label to *"Uploading profile photo…"*. The zone must not be focusable during upload.
+
+When State=Uploaded, update aria-label to *"Profile photo uploaded. Hover or focus to replace or remove."* This tells keyboard users there are hidden actions available.
+
+The Replace and Remove buttons in the overlay (State=Uploaded-hover) must always be keyboard-reachable via Tab, even when the overlay is visually hidden. Use CSS (opacity: 0; pointer-events: none) rather than display: none or visibility: hidden so they remain in the focus order.
+
+The Replace button must have aria-label=*"Replace profile photo"* and the Remove button aria-label=*"Remove profile photo"* — not just *"Replace"* and *"Remove"* without context.
+
+When State=Error, the error message must be associated via aria-describedby and placed in an aria-live=*"polite"* region.
+
+When State=Disable, the zone must have aria-disabled=*"true"* and tabindex=*"-1"*.
+
+The image preview is decorative — set aria-hidden=*"true"* on the <img> element inside the zone, since the zone's aria-label already communicates the current state.
+
+For touch devices, the Replace and Remove controls that live outside the hover overlay must also have descriptive aria-label attributes.
+<!-- END:xui-mcp-instructions:image-uploader -->
+
 ## Installation
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-image-uploader",
-  "version": "0.174.3",
+  "version": "0.176.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-core": "0.174.3",
-    "@xsolla/xui-icons-base": "0.174.3",
-    "@xsolla/xui-primitives-core": "0.174.3",
-    "@xsolla/xui-spinner": "0.174.3"
+    "@xsolla/xui-core": "0.176.0",
+    "@xsolla/xui-icons-base": "0.176.0",
+    "@xsolla/xui-primitives-core": "0.176.0",
+    "@xsolla/xui-spinner": "0.176.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0"