@xsolla/xui-uploader 0.99.0 → 0.100.0

package/README.md

@@ -1,36 +1,276 @@
-# @xsolla/xui-uploader
+---
+title: Uploader
+subtitle: File upload component.
+description: A cross-platform React file uploader component with file selection, preview, and management capabilities.
+---
 
-File upload control with a trigger button and selected file list.
+# Uploader
+
+A cross-platform React file uploader component that provides a button to select files, displays selected files, and allows removing them.
 
 ## Installation
 
 ```bash
+npm install @xsolla/xui-uploader
+# or
 yarn add @xsolla/xui-uploader
 ```
 
-## Usage
+## Demo
+
+### Basic Uploader
 
 ```tsx
+import * as React from 'react';
+import { Uploader } from '@xsolla/xui-uploader';
+
+export default function BasicUploader() {
+  return (
+    <Uploader
+      label="Upload file"
+      onFilesChange={(files) => console.log('Selected:', files)}
+    />
+  );
+}
+```
+
+### Multiple Files
+
+```tsx
+import * as React from 'react';
+import { Uploader } from '@xsolla/xui-uploader';
+
+export default function MultipleFiles() {
+  return (
+    <Uploader
+      label="Upload documents"
+      placeholder="Select multiple files"
+      multiple
+      onFilesChange={(files) => console.log('Files:', files)}
+    />
+  );
+}
+```
+
+### Accept Specific Types
+
+```tsx
+import * as React from 'react';
+import { Uploader } from '@xsolla/xui-uploader';
+
+export default function ImageUploader() {
+  return (
+    <Uploader
+      label="Upload image"
+      placeholder="Select image file"
+      accept=".jpg,.jpeg,.png,.gif"
+      onFilesChange={(files) => console.log('Images:', files)}
+    />
+  );
+}
+```
+
+## Anatomy
+
+```jsx
 import { Uploader } from '@xsolla/xui-uploader';
 
 <Uploader
-  label="Attachments"
-  accept=".jpg,.png,.pdf"
-  multiple
-  onFilesChange={(files) => console.log(files)}
+  label="Label"                     // Label above button
+  placeholder="Select files"        // Button text
+  accept=".pdf,.doc"                // Accepted file types
+  multiple={false}                  // Allow multiple selection
+  disabled={false}                  // Disabled state
+  size="md"                          // Button size
+  onFilesChange={handleFiles}       // File change callback
 />
 ```
 
-## Props
+## Examples
+
+### Document Upload
+
+```tsx
+import * as React from 'react';
+import { Uploader } from '@xsolla/xui-uploader';
+
+export default function DocumentUpload() {
+  const [files, setFiles] = React.useState<File[]>([]);
+
+  return (
+    <div>
+      <Uploader
+        label="Legal documents"
+        placeholder="Upload PDF documents"
+        accept=".pdf"
+        multiple
+        onFilesChange={setFiles}
+      />
+      {files.length > 0 && (
+        <p style={{ marginTop: 8 }}>
+          {files.length} file(s) selected
+        </p>
+      )}
+    </div>
+  );
+}
+```
+
+### Profile Image Upload
+
+```tsx
+import * as React from 'react';
+import { Uploader } from '@xsolla/xui-uploader';
+
+export default function ProfileImageUpload() {
+  const handleImageUpload = (files: File[]) => {
+    if (files.length > 0) {
+      const file = files[0];
+      // Create preview URL
+      const previewUrl = URL.createObjectURL(file);
+      console.log('Preview:', previewUrl);
+    }
+  };
+
+  return (
+    <div style={{ maxWidth: 300 }}>
+      <Uploader
+        label="Profile picture"
+        placeholder="Choose image"
+        accept="image/*"
+        onFilesChange={handleImageUpload}
+        size="sm"
+      />
+      <p style={{ fontSize: 12, color: '#666', marginTop: 4 }}>
+        Recommended: Square image, at least 200x200px
+      </p>
+    </div>
+  );
+}
+```
+
+### Form with File Upload
+
+```tsx
+import * as React from 'react';
+import { Uploader } from '@xsolla/xui-uploader';
+import { Input } from '@xsolla/xui-input';
+import { Textarea } from '@xsolla/xui-textarea';
+import { Button } from '@xsolla/xui-button';
+
+export default function FormWithUpload() {
+  const [files, setFiles] = React.useState<File[]>([]);
+
+  const handleSubmit = () => {
+    const formData = new FormData();
+    files.forEach((file) => formData.append('attachments', file));
+    console.log('Submitting with', files.length, 'files');
+  };
+
+  return (
+    <form
+      style={{ display: 'flex', flexDirection: 'column', gap: 16, maxWidth: 400 }}
+      onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}
+    >
+      <Input label="Subject" placeholder="Enter subject" />
+      <Textarea label="Message" placeholder="Enter your message" />
+      <Uploader
+        label="Attachments"
+        placeholder="Add attachments"
+        multiple
+        onFilesChange={setFiles}
+      />
+      <Button type="submit">Submit</Button>
+    </form>
+  );
+}
+```
+
+### Different Sizes
+
+```tsx
+import * as React from 'react';
+import { Uploader } from '@xsolla/xui-uploader';
+
+export default function UploaderSizes() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <Uploader size="xs" placeholder="Extra small" />
+      <Uploader size="sm" placeholder="Small" />
+      <Uploader size="md" placeholder="Medium" />
+      <Uploader size="lg" placeholder="Large" />
+      <Uploader size="xl" placeholder="Extra large" />
+    </div>
+  );
+}
+```
+
+### Disabled State
+
+```tsx
+import * as React from 'react';
+import { Uploader } from '@xsolla/xui-uploader';
+
+export default function DisabledUploader() {
+  return (
+    <Uploader
+      label="Upload (disabled)"
+      placeholder="Cannot upload files"
+      disabled
+    />
+  );
+}
+```
+
+## API Reference
 
 ### Uploader
 
+**UploaderProps:**
+
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | — | Label rendered above the upload button |
-| `placeholder` | `string` | `"Select files to upload"` | Button text when no files are selected |
-| `accept` | `string` | — | Accepted file types (e.g. `".jpg,.png"`) |
-| `multiple` | `boolean` | `false` | Allow selecting multiple files |
-| `onFilesChange` | `(files: File[]) => void` | — | Callback fired when the file list changes |
-| `disabled` | `boolean` | `false` | Disables the control |
-| `size` | `"xl" \| "lg" \| "md" \| "sm" \| "xs"` | `"md"` | Size of the upload button |
+| :--- | :--- | :------ | :---------- |
+| label | `string` | - | Label text above the button. |
+| placeholder | `string` | `"Select files to upload"` | Button text. |
+| accept | `string` | - | Accepted file types (e.g., ".jpg,.png"). |
+| multiple | `boolean` | `false` | Allow multiple file selection. |
+| disabled | `boolean` | `false` | Disabled state. |
+| size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Button size. |
+| onFilesChange | `(files: File[]) => void` | - | Callback when files change. |
+
+## File List Display
+
+When files are selected, they appear below the button with:
+
+- File icon
+- File name (truncated if too long)
+- Remove button (X icon)
+
+Removing a file updates the list and calls `onFilesChange` with the updated array.
+
+## Accept Patterns
+
+| Pattern | Description |
+| :------ | :---------- |
+| `.pdf` | PDF files only |
+| `.jpg,.jpeg,.png` | Specific image formats |
+| `image/*` | All image types |
+| `video/*` | All video types |
+| `.doc,.docx,.pdf` | Multiple document types |
+
+## Behavior
+
+- Click button to open native file picker
+- Multiple selection when `multiple` is true
+- Files accumulate when `multiple` is true (new selections add to existing)
+- Files replace when `multiple` is false
+- Each file can be removed individually
+- Hidden native input, styled button
+
+## Accessibility
+
+- Button is keyboard accessible
+- File input is properly associated with the button
+- Remove buttons have appropriate labels
+- Disabled state prevents interaction
+- File list is accessible to screen readers

package/package.json

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