@xsolla/xui-progress-bar 0.174.3 → 0.175.0

package/README.md

@@ -1,6 +1,69 @@
 # ProgressBar
 
 A cross-platform React linear progress bar with optional label, status icon, helper text, and error state.
+<!-- BEGIN:xui-mcp-instructions:progress-bar -->
+A visual indicator that communicates how far along a process is. Displays a filled track proportional to the current value, with optional label, helper text, status icon, and icon pair. Supports three sizes and five semantic states including success and error.
+
+### When to use
+
+To show progress of a long-running operation — file upload, form completion, onboarding steps, level progression
+- When the user needs to understand how much work remains before a task finishes
+- When communicating a measurable quantity against a known maximum (e.g. storage used, quiz score, achievement progress)
+- When a process has a defined success or failure outcome that should be surfaced inline
+
+### When not to use
+
+- For indeterminate loading (duration unknown) — use a Spinner or skeleton instead
+- For binary on/off states — use a Toggle or Checkbox
+- For navigation between steps
+- When the value does not represent progress toward a goal — use a data visualisation chart instead
+
+### Content guidelines
+
+Label — describe what is progressing, not the percentage. *"Uploading file"* not *"50% complete"*. The bar communicates the percentage visually.
+
+Helper text — use a concrete format: *"1.2 GB of 5 GB"*, *"Step 3 of 8"*, *"12 seconds remaining"*. Avoid vague text like *"Loading…"* if a specific value is available.
+
+Error helper text — be specific about what failed and what the user should do: *"Upload failed — file exceeds 50 MB limit"*, not *"Error"*.
+
+Success helper text — confirm completion positively: *"Upload complete"*, *"All steps finished"*.
+
+Label length — keep the label to a single line. If it wraps, shorten or move to a heading outside the component.
+
+### Behaviour guidelines
+
+Value updates — the filled track should animate smoothly when the value changes. Use a CSS transition on width (left-to-right direction). Avoid abrupt jumps except on initial render.
+
+Direction — progress always flows left to right in LTR layouts. Mirror to right-to-left in RTL contexts.
+
+0% state — when value is 0%, the indicator may be invisible or show a minimal visible stub (1–2px) so the user can perceive the track exists. Do not omit the track entirely.
+
+100% vs Success — reaching 100% fill does not automatically trigger the Success state. Switch to Percent=Success only after the process is confirmed complete on the backend. This prevents false positives during the final data transfer window.
+
+Error state — switch to Percent=Error immediately when a failure is detected. The fill level at the point of failure should be preserved — do not reset to 0%. Pair with Helper text explaining the error and an action to recover (e.g. *"Retry"*).
+
+Indeterminate — if the duration is unknown, do not use Progress bar. Use a Spinner or an animated skeleton instead. Do not fake progress by auto-incrementing the bar without real data.
+
+Real-time updates — when progress is driven by a WebSocket or polling interval, throttle UI updates to no more than once every 100–200ms to avoid visual jitter on fast transfers.
+
+Completion transition — after reaching Success, consider keeping the bar visible for 1–2 seconds before replacing it with final content. This gives users time to register the completed state.
+
+Multiple bars — when showing several progress bars simultaneously (e.g. a file upload queue), keep all bars the same size and align them in a vertical list with consistent spacing.
+
+### Accessibility
+
+The progress element must use role=*"progressbar"* with aria-valuenow, aria-valuemin=*"0"*, and aria-valuemax=*"100"*.
+
+Provide aria-label or aria-labelledby pointing to the Label text so screen readers announce what is progressing.
+
+Link the Helper text via aria-describedby so additional context (including error messages) is announced.
+
+Enable Status-icon for terminal states (Success / Error) to communicate state through shape, not colour alone — this satisfies WCAG 1.4.1 (Use of Colour).
+
+For Percent=Error, the error description in Helper text must be programmatically associated with the component so assistive technology surfaces it without the user needing to navigate separately.
+
+When the value updates dynamically, use aria-live=*"polite"* on the helper text region so screen readers announce the change without interrupting current speech.
+<!-- END:xui-mcp-instructions:progress-bar -->
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-progress-bar",
-  "version": "0.174.3",
+  "version": "0.175.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -10,9 +10,9 @@
     "build:native": "PLATFORM=native tsup"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.174.3",
-    "@xsolla/xui-icons": "0.174.3",
-    "@xsolla/xui-primitives-core": "0.174.3"
+    "@xsolla/xui-core": "0.175.0",
+    "@xsolla/xui-icons": "0.175.0",
+    "@xsolla/xui-primitives-core": "0.175.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",