@xsolla/xui-image 0.148.0 → 0.148.1

package/README.md

@@ -0,0 +1,240 @@
+# Image
+
+A cross-platform React image component with built-in aspect ratio presets and support for overlay content. Maintains consistent dimensions across different image sizes.
+
+## Installation
+
+```bash
+npm install @xsolla/xui-image
+# or
+yarn add @xsolla/xui-image
+```
+
+## Demo
+
+### Basic Image
+
+```tsx
+import * as React from 'react';
+import { Image } from '@xsolla/xui-image';
+
+export default function BasicImage() {
+  return (
+    <Image
+      src="https://example.com/photo.jpg"
+      alt="Sample photo"
+    />
+  );
+}
+```
+
+### With Aspect Ratio
+
+```tsx
+import * as React from 'react';
+import { Image } from '@xsolla/xui-image';
+
+export default function RatioImage() {
+  return (
+    <Image
+      src="https://example.com/photo.jpg"
+      alt="16:9 photo"
+      ratio="16:9"
+      width={400}
+    />
+  );
+}
+```
+
+### With Border Radius
+
+```tsx
+import * as React from 'react';
+import { Image } from '@xsolla/xui-image';
+
+export default function RoundedImage() {
+  return (
+    <Image
+      src="https://example.com/photo.jpg"
+      alt="Rounded photo"
+      ratio="1:1"
+      width={200}
+      borderRadius={16}
+    />
+  );
+}
+```
+
+### With Overlay Slot
+
+```tsx
+import * as React from 'react';
+import { Image } from '@xsolla/xui-image';
+
+export default function OverlayImage() {
+  return (
+    <Image
+      src="https://example.com/photo.jpg"
+      alt="Photo with overlay"
+      ratio="16:9"
+      width={400}
+      slot={
+        <div style={{
+          background: 'rgba(0,0,0,0.5)',
+          color: 'white',
+          padding: 16,
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}>
+          Overlay Content
+        </div>
+      }
+    />
+  );
+}
+```
+
+## Anatomy
+
+```jsx
+import { Image } from '@xsolla/xui-image';
+
+<Image
+  src="image-url.jpg"        // Image source URL
+  alt="Description"          // Alt text for accessibility
+  ratio="1:1"                // Aspect ratio preset
+  customRatio="21 / 9"       // Custom ratio (when ratio="Custom")
+  width={200}                // Container width
+  borderRadius={0}           // Border radius
+  slot={<Overlay />}         // Overlay content
+  style={{}}                 // Container styles
+  imageStyle={{}}            // Image element styles
+/>
+```
+
+## Examples
+
+### Aspect Ratio Gallery
+
+```tsx
+import * as React from 'react';
+import { Image } from '@xsolla/xui-image';
+
+export default function RatioGallery() {
+  const src = "https://example.com/photo.jpg";
+
+  return (
+    <div style={{ display: 'flex', gap: 16, flexWrap: 'wrap' }}>
+      <div>
+        <p>1:1 (Square)</p>
+        <Image src={src} ratio="1:1" width={150} />
+      </div>
+      <div>
+        <p>16:9 (Widescreen)</p>
+        <Image src={src} ratio="16:9" width={200} />
+      </div>
+      <div>
+        <p>4:3 (Standard)</p>
+        <Image src={src} ratio="4:3" width={180} />
+      </div>
+      <div>
+        <p>3:2 (Photo)</p>
+        <Image src={src} ratio="3:2" width={180} />
+      </div>
+      <div>
+        <p>2:3 (Portrait)</p>
+        <Image src={src} ratio="2:3" width={120} />
+      </div>
+      <div>
+        <p>9:16 (Story)</p>
+        <Image src={src} ratio="9:16" width={100} />
+      </div>
+    </div>
+  );
+}
+```
+
+### Custom Aspect Ratio
+
+```tsx
+import * as React from 'react';
+import { Image } from '@xsolla/xui-image';
+
+export default function CustomRatioImage() {
+  return (
+    <Image
+      src="https://example.com/ultrawide.jpg"
+      alt="Ultra-wide photo"
+      ratio="Custom"
+      customRatio="21 / 9"
+      width={400}
+    />
+  );
+}
+```
+
+### Placeholder State
+
+```tsx
+import * as React from 'react';
+import { Image } from '@xsolla/xui-image';
+
+export default function PlaceholderImage() {
+  return (
+    <Image
+      ratio="16:9"
+      width={400}
+      slot={
+        <span style={{ color: '#999' }}>Loading...</span>
+      }
+    />
+  );
+}
+```
+
+## API Reference
+
+### Image
+
+**Image Props:**
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| src | `string` | - | Image source URL. |
+| alt | `string` | `""` | Alt text for accessibility. |
+| ratio | `ImageRatio` | `"1:1"` | Aspect ratio preset. |
+| customRatio | `string \| number` | - | Custom ratio when ratio is "Custom". |
+| width | `number \| string` | `"100%"` | Container width. |
+| borderRadius | `number \| string` | `0` | Border radius of container. |
+| slot | `ReactNode` | - | Overlay content (centered). |
+| style | `CSSProperties` | - | Container styles. |
+| imageStyle | `CSSProperties` | - | Image element styles. |
+
+**ImageRatio Type:**
+
+```typescript
+type ImageRatio =
+  | "1:1"     // Square
+  | "2:3"     // Portrait
+  | "3:2"     // Landscape photo
+  | "16:9"    // Widescreen
+  | "4:3"     // Standard
+  | "9:16"    // Story/mobile
+  | "Custom"; // Use customRatio
+```
+
+## Behavior
+
+- Image fills container with `object-fit: cover`
+- Background color shows when image hasn't loaded
+- Slot content overlays the image (centered)
+- Maintains aspect ratio regardless of source image dimensions
+
+## Accessibility
+
+- Always provide meaningful `alt` text
+- Decorative images can use `alt=""`
+- Slot content should be accessible if interactive

package/package.json

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