@xsolla/xui-image-uploader 0.147.1

package/README.md

@@ -0,0 +1,258 @@
+# ImageUploader
+
+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, loading and error states, and a wide horizontal layout.
+
+## Installation
+
+```bash
+npm install @xsolla/xui-image-uploader
+# or
+yarn add @xsolla/xui-image-uploader
+```
+
+## Demo
+
+### Basic (Uncontrolled)
+
+```tsx
+import * as React from 'react';
+import { ImageUploader, type ImageUploaderFile } from '@xsolla/xui-image-uploader';
+
+export default function Basic() {
+  const handleUpload = (file: ImageUploaderFile) => {
+    console.log('Picked file:', file.name, file.size);
+  };
+
+  return <ImageUploader onUpload={handleUpload} />;
+}
+```
+
+### Controlled
+
+```tsx
+import * as React from 'react';
+import {
+  ImageUploader,
+  type ImageUploaderValue,
+} from '@xsolla/xui-image-uploader';
+
+export default function Controlled() {
+  const [value, setValue] = React.useState<ImageUploaderValue | null>(null);
+
+  return (
+    <ImageUploader
+      value={value}
+      onChange={setValue}
+      placeholder="Upload avatar"
+    />
+  );
+}
+```
+
+### Wide View with Description
+
+```tsx
+import * as React from 'react';
+import { ImageUploader } from '@xsolla/xui-image-uploader';
+
+export default function WideView() {
+  return (
+    <ImageUploader
+      wideView
+      placeholder="Upload cover image"
+      description="PNG or JPG, up to 5 MB"
+    />
+  );
+}
+```
+
+### Loading State
+
+```tsx
+import * as React from 'react';
+import {
+  ImageUploader,
+  type ImageUploaderFile,
+} from '@xsolla/xui-image-uploader';
+
+export default function WithLoading() {
+  const [loading, setLoading] = React.useState(false);
+
+  const handleUpload = async (file: ImageUploaderFile) => {
+    setLoading(true);
+    try {
+      await uploadToServer(file.file);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <ImageUploader
+      loading={loading}
+      uploadingPlaceholder="Uploading…"
+      onUpload={handleUpload}
+    />
+  );
+}
+```
+
+### Error State
+
+```tsx
+import * as React from 'react';
+import { ImageUploader } from '@xsolla/xui-image-uploader';
+
+export default function WithError() {
+  return (
+    <ImageUploader
+      placeholder="cover.png"
+      errorMessage="File is too large (max 5 MB)."
+    />
+  );
+}
+```
+
+### React Native (Custom Picker)
+
+On native there is no DOM `<input type="file">`. Pass an `openPicker` prop that
+returns a normalized `ImageUploaderFile` (e.g. wrapping `expo-image-picker` or
+`react-native-image-picker`).
+
+```tsx
+import * as React from 'react';
+import * as ImagePicker from 'expo-image-picker';
+import {
+  ImageUploader,
+  type ImageUploaderFile,
+} from '@xsolla/xui-image-uploader';
+
+export default function Native() {
+  const openPicker = async (): Promise<ImageUploaderFile | null> => {
+    const result = await ImagePicker.launchImageLibraryAsync({
+      mediaTypes: ImagePicker.MediaTypeOptions.Images,
+    });
+    if (result.canceled) return null;
+    const asset = result.assets[0];
+    return {
+      name: asset.fileName ?? 'image',
+      size: asset.fileSize ?? 0,
+      uri: asset.uri,
+      mimeType: asset.mimeType,
+    };
+  };
+
+  return <ImageUploader openPicker={openPicker} />;
+}
+```
+
+## Anatomy
+
+```
++--------------------------+
+|                          |
+|         [Image]          |  <- icon (or Spinner while loading)
+|         Upload           |  <- placeholder
+|     PNG/JPG, up to 5MB   |  <- description (wideView only)
+|                          |
++--------------------------+
+  File is too large…         <- errorMessage (when present)
+```
+
+When a file has been uploaded, the box renders the image preview and reveals a
+trash-can affordance over a dimming scrim on hover; clicking (or tapping)
+removes the image. On touch and React Native devices — where there is no hover
+— the trash overlay is shown unconditionally so the delete affordance is
+always discoverable.
+
+## API Reference
+
+### ImageUploader
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| size | `"xl" \| "lg" \| "md" \| "sm" \| "xs"` | `"xl"` | Visual size of the uploader. |
+| placeholder | `string` | `"Upload"` | Label shown under the icon (or filename in error state). |
+| uploadingPlaceholder | `string` | `"Uploading"` | Label shown while `loading` is true. |
+| description | `React.ReactNode` | - | Helper text below the placeholder. Only rendered when `wideView` is true. |
+| errorMessage | `string` | - | Error message — when provided, the component renders in the error state. |
+| wideView | `boolean` | `false` | Use the horizontal layout (`wideWidth` from sizing tokens). |
+| disabled | `boolean` | `false` | Disabled state. |
+| loading | `boolean` | `false` | Controlled loading state (shows spinner + uploading label). |
+| value | `ImageUploaderValue \| null` | - | Controlled value. When provided, the component reflects this value. |
+| onUpload | `(file: ImageUploaderFile) => void` | - | Fires when the user picks (or drops) a file. Use this to perform the actual upload. |
+| onChange | `(value: ImageUploaderValue \| null) => void` | - | Fires when the displayed value changes — on file pick (with a local data-URL preview) and on remove (`null`). |
+| onDelete | `() => void` | - | Fires when the user removes the image (trash click / clear). |
+| accept | `string` | `"image/*"` | Accepted MIME types for the file input (web only). |
+| openPicker | `() => Promise<ImageUploaderFile \| null>` | - | Native file picker hook. Required on native (no DOM `<input type="file">`). On web, omit this and the component falls back to a hidden file input. |
+| themeMode | `ThemeMode` | - | Override the theme mode for this instance. |
+| themeProductContext | `ThemeProductContext` | - | Override the product theme context for this instance. |
+
+### ImageUploaderValue
+
+Controlled value shape.
+
+```ts
+interface ImageUploaderValue {
+  filename: string;
+  url?: string;
+}
+```
+
+> Loading and error states are driven by the `loading` and `errorMessage`
+> props, not by fields on `ImageUploaderValue`.
+
+### ImageUploaderFile
+
+Normalized file shape produced by the platform picker / drag-drop pipeline.
+On web, `uri` is a data-URL and the original DOM `File` is passed through for
+consumers that need it (e.g. to upload via `FormData` / `fetch`). On native,
+`uri` is a file URI and `file` is omitted.
+
+```ts
+interface ImageUploaderFile {
+  name: string;
+  size: number;
+  uri: string;
+  mimeType?: string;
+  /** The original DOM File (web only) */
+  file?: File;
+}
+```
+
+## Platform Support
+
+This package works on both **web** and **React Native**. The component uses
+cross-platform primitives (`Box`, `Text`, `Spinner`) and gates web-only APIs
+(DOM file input, drag-and-drop, `FileReader`) behind an `isWeb` check. On
+native, supply an `openPicker` prop to integrate with your image picker
+library of choice.
+
+### Touch / Mobile
+
+On touch web (detected via `matchMedia("(hover: none)")`) and on React Native,
+the component skips the hover-only delete affordance and always shows the
+trash overlay over the image preview, ensuring the remove action is reachable
+without a pointer.
+
+### Layout
+
+In `wideView`, the component stretches to fill its parent (`width: 100%`) up
+to the design max from the size token (`wideWidth`), so it scales gracefully
+on narrow viewports while capping on desktop. The square (non-wide) variants
+use fixed pixel dimensions from the size tokens.
+
+## Accessibility
+
+- The picker surface is rendered as a `<button>` on web with an accessible
+  label that reflects the current state (`"Upload"`, `"Uploading"`, or
+  `"Remove image: <filename>"`).
+- `aria-busy` is set while `loading` is true.
+- `aria-invalid` is set in the error state and the error message is linked
+  via `aria-describedby` (and rendered with `role="alert"`).
+- The `description` element (when present) is linked via `aria-describedby`.
+- Decorative icons and the dimming scrim are marked `aria-hidden`.
+- Focus styling only appears for keyboard focus (`:focus-visible`), not for
+  pointer focus left over after the native picker is dismissed.
+- The hidden file input is reset after every selection so the same file can
+  be re-selected to retry a failed upload.

package/native/index.d.mts

@@ -0,0 +1,65 @@
+import React from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+
+type ImageUploaderSize = "xl" | "lg" | "md" | "sm" | "xs";
+/** Controlled value shape. */
+interface ImageUploaderValue {
+    filename: string;
+    url?: string;
+}
+/**
+ * Normalized file shape produced by the platform picker / drag-drop pipeline.
+ * - `uri` is a data-URL on web and a file URI on native.
+ * - On web, the original `File` is passed through for consumers that need it
+ *   (e.g. to upload via FormData / fetch).
+ */
+type ImageUploaderFile = {
+    name: string;
+    size: number;
+    uri: string;
+    mimeType?: string;
+    /** The original DOM File (web only) */
+    file?: File;
+};
+interface ImageUploaderProps extends ThemeOverrideProps {
+    /** Size of the uploader. Figma default is `xl`. */
+    size?: ImageUploaderSize;
+    /** Placeholder text shown under the icon (e.g. "Upload" or filename in error). */
+    placeholder?: string;
+    /** Placeholder text shown while the file is uploading. */
+    uploadingPlaceholder?: string;
+    /** Description below the placeholder. Only rendered when `wideView` is true. Accepts a string or a custom React node. */
+    description?: React.ReactNode;
+    /** Error message — when provided, component renders in the error state. */
+    errorMessage?: string;
+    /** Wide view (horizontal layout). When true, box uses `wideWidth` from sizing. */
+    wideView?: boolean;
+    /** Disabled state. */
+    disabled?: boolean;
+    /** Controlled loading state (shows spinner + "Uploading" label). */
+    loading?: boolean;
+    /** Controlled value. When provided, the component reflects this value. */
+    value?: ImageUploaderValue | null;
+    /**
+     * Fires when the user picks (or drops) a file. Use this to perform the
+     * actual upload — the component itself does no I/O.
+     */
+    onUpload?: (file: ImageUploaderFile) => void;
+    /**
+     * Fires when the displayed value changes — on file pick (with a local
+     * data-URL preview) and on remove (`null`).
+     */
+    onChange?: (value: ImageUploaderValue | null) => void;
+    /** Fires when the user removes the image (trash click / clear). */
+    onDelete?: () => void;
+    /** Accepted file types (web only — ignored on native). */
+    accept?: string;
+    /**
+     * Native file picker hook. Required on native (no DOM `<input type="file">`).
+     * On web, omit this and the component falls back to a hidden file input.
+     */
+    openPicker?: () => Promise<ImageUploaderFile | null>;
+}
+declare const ImageUploader: React.ForwardRefExoticComponent<ImageUploaderProps & React.RefAttributes<HTMLInputElement>>;
+
+export { ImageUploader, type ImageUploaderFile, type ImageUploaderProps, type ImageUploaderSize, type ImageUploaderValue };

package/native/index.d.ts

@@ -0,0 +1,65 @@
+import React from 'react';
+import { ThemeOverrideProps } from '@xsolla/xui-core';
+
+type ImageUploaderSize = "xl" | "lg" | "md" | "sm" | "xs";
+/** Controlled value shape. */
+interface ImageUploaderValue {
+    filename: string;
+    url?: string;
+}
+/**
+ * Normalized file shape produced by the platform picker / drag-drop pipeline.
+ * - `uri` is a data-URL on web and a file URI on native.
+ * - On web, the original `File` is passed through for consumers that need it
+ *   (e.g. to upload via FormData / fetch).
+ */
+type ImageUploaderFile = {
+    name: string;
+    size: number;
+    uri: string;
+    mimeType?: string;
+    /** The original DOM File (web only) */
+    file?: File;
+};
+interface ImageUploaderProps extends ThemeOverrideProps {
+    /** Size of the uploader. Figma default is `xl`. */
+    size?: ImageUploaderSize;
+    /** Placeholder text shown under the icon (e.g. "Upload" or filename in error). */
+    placeholder?: string;
+    /** Placeholder text shown while the file is uploading. */
+    uploadingPlaceholder?: string;
+    /** Description below the placeholder. Only rendered when `wideView` is true. Accepts a string or a custom React node. */
+    description?: React.ReactNode;
+    /** Error message — when provided, component renders in the error state. */
+    errorMessage?: string;
+    /** Wide view (horizontal layout). When true, box uses `wideWidth` from sizing. */
+    wideView?: boolean;
+    /** Disabled state. */
+    disabled?: boolean;
+    /** Controlled loading state (shows spinner + "Uploading" label). */
+    loading?: boolean;
+    /** Controlled value. When provided, the component reflects this value. */
+    value?: ImageUploaderValue | null;
+    /**
+     * Fires when the user picks (or drops) a file. Use this to perform the
+     * actual upload — the component itself does no I/O.
+     */
+    onUpload?: (file: ImageUploaderFile) => void;
+    /**
+     * Fires when the displayed value changes — on file pick (with a local
+     * data-URL preview) and on remove (`null`).
+     */
+    onChange?: (value: ImageUploaderValue | null) => void;
+    /** Fires when the user removes the image (trash click / clear). */
+    onDelete?: () => void;
+    /** Accepted file types (web only — ignored on native). */
+    accept?: string;
+    /**
+     * Native file picker hook. Required on native (no DOM `<input type="file">`).
+     * On web, omit this and the component falls back to a hidden file input.
+     */
+    openPicker?: () => Promise<ImageUploaderFile | null>;
+}
+declare const ImageUploader: React.ForwardRefExoticComponent<ImageUploaderProps & React.RefAttributes<HTMLInputElement>>;
+
+export { ImageUploader, type ImageUploaderFile, type ImageUploaderProps, type ImageUploaderSize, type ImageUploaderValue };