@xsolla/xui-progress-bar 0.149.1 → 0.151.0

package/README.md

@@ -1,79 +1,124 @@
-# Progress Bar
+# ProgressBar
 
-A cross-platform React circular progress bar component for displaying completion status. Useful for showing task progress or loading states with percentage.
+A cross-platform React linear progress bar with optional label, status icon, helper text, and error state.
 
 ## Installation
 
 ```bash
 npm install @xsolla/xui-progress-bar
-# or
-yarn add @xsolla/xui-progress-bar
 ```
 
-## Demo
+## Imports
 
-### Basic Progress Bar
+```tsx
+import { ProgressBar } from '@xsolla/xui-progress-bar';
+```
+
+## Quick start
 
 ```tsx
 import * as React from 'react';
 import { ProgressBar } from '@xsolla/xui-progress-bar';
 
-export default function BasicProgressBar() {
-  return <ProgressBar value={75} />;
+export default function QuickStart() {
+  return <ProgressBar percent={60} label="Uploading" />;
 }
 ```
 
-### Progress Bar Sizes
+## API Reference
+
+### `<ProgressBar>`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `percent` | `number` | `0` | Progress value, clamped to `0..100`. |
+| `size` | `"xl" \| "lg" \| "md" \| "sm" \| "xs" \| "l" \| "m" \| "s"` | `"m"` | Bar height and label/helper typography. Long-form (`xl`, `lg`, `md`, `sm`, `xs`) and short-form (`l`, `m`, `s`) values are both accepted. Default `"m"` is equivalent to long-form `"md"`. |
+| `state` | `"default" \| "success" \| "error"` | `"default"` | Drives bar colour, status icon, and helper styling. |
+| `label` | `string` | — | Label rendered above the bar. |
+| `showLabel` | `boolean` | `true` | Toggles the entire label row (label, info icon, status icon). |
+| `showInfoIcon` | `boolean` | `false` | Adds an info icon next to the label. |
+| `showStatusIcon` | `boolean` | `true` | Renders the default status icon (`Check` for success, `AlertCircle` for error). |
+| `helperText` | `string` | — | Helper text rendered below the bar. |
+| `errorMessage` | `string` | — | Replaces `helperText` when `state === "error"`. |
+| `labelIcon` | `ReactNode` | — | Icon rendered to the left of the label. |
+| `statusIcon` | `ReactNode` | — | Override for the default status icon. |
+
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
+
+## Examples
+
+### States
 
 ```tsx
 import * as React from 'react';
 import { ProgressBar } from '@xsolla/xui-progress-bar';
 
-export default function ProgressBarSizes() {
+export default function ProgressStates() {
   return (
-    <div style={{ display: 'flex', gap: 24, alignItems: 'center' }}>
-      <ProgressBar value={60} size="sm" />
-      <ProgressBar value={60} size="md" />
-      <ProgressBar value={60} size="lg" />
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <ProgressBar percent={40} label="Default" />
+      <ProgressBar percent={100} state="success" label="Success" helperText="Done" />
+      <ProgressBar percent={70} state="error" label="Failed" errorMessage="Network error" />
     </div>
   );
 }
 ```
 
-### Animated Progress
+### Sizes
 
 ```tsx
 import * as React from 'react';
 import { ProgressBar } from '@xsolla/xui-progress-bar';
 
-export default function AnimatedProgress() {
-  const [progress, setProgress] = React.useState(0);
-
-  React.useEffect(() => {
-    const timer = setInterval(() => {
-      setProgress((prev) => (prev >= 100 ? 0 : prev + 10));
-    }, 500);
-    return () => clearInterval(timer);
-  }, []);
-
-  return <ProgressBar value={progress} />;
+export default function ProgressSizes() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <ProgressBar percent={50} size="xs" />
+      <ProgressBar percent={50} size="sm" />
+      <ProgressBar percent={50} size="md" />
+      <ProgressBar percent={50} size="lg" />
+      <ProgressBar percent={50} size="xl" />
+    </div>
+  );
 }
 ```
 
-## API Reference
+### With helper text and info icon
 
-### ProgressBar
+```tsx
+import * as React from 'react';
+import { ProgressBar } from '@xsolla/xui-progress-bar';
 
-**ProgressBar Props:**
+export default function ProgressHelpers() {
+  return (
+    <ProgressBar
+      percent={35}
+      label="Uploading assets"
+      helperText="3 of 8 files complete"
+      showInfoIcon
+    />
+  );
+}
+```
 
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| value | `number` | `0` | Progress value (0-100). |
-| size | `"sm" \| "md" \| "lg"` | `"md"` | Size of the progress bar. |
+### Animated
 
-## Theming
+```tsx
+import * as React from 'react';
+import { ProgressBar } from '@xsolla/xui-progress-bar';
 
-```typescript
-theme.colors.background.brand.primary  // Progress fill color
-theme.colors.border.secondary          // Track color
+export default function AnimatedProgress() {
+  const [percent, setPercent] = React.useState(0);
+  React.useEffect(() => {
+    const id = setInterval(() => setPercent((p) => (p >= 100 ? 0 : p + 10)), 500);
+    return () => clearInterval(id);
+  }, []);
+  return <ProgressBar percent={percent} label={`${percent}%`} />;
+}
 ```
+
+## Accessibility
+
+- The bar has `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`.
+- Helper text and error messages are linked via `aria-describedby`.
+- Provide a `label` to give the bar an accessible name.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-progress-bar",
-  "version": "0.149.1",
+  "version": "0.151.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.149.1",
-    "@xsolla/xui-icons": "0.149.1",
-    "@xsolla/xui-primitives-core": "0.149.1"
+    "@xsolla/xui-core": "0.151.0",
+    "@xsolla/xui-icons": "0.151.0",
+    "@xsolla/xui-primitives-core": "0.151.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",