@xsolla/xui-image 0.99.0 → 0.100.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +226 -16
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,36 +1,246 @@
1
- # @xsolla/xui-image
1
+ ---
2
+ title: Image
3
+ subtitle: An image component with aspect ratio support.
4
+ description: A cross-platform React image component with built-in aspect ratio presets and overlay slots.
5
+ ---
2
6
 
3
- Image component with aspect ratio control and an optional overlay slot.
7
+ # Image
8
+
9
+ A cross-platform React image component with built-in aspect ratio presets and support for overlay content. Maintains consistent dimensions across different image sizes.
4
10
 
5
11
  ## Installation
6
12
 
7
13
  ```bash
14
+ npm install @xsolla/xui-image
15
+ # or
8
16
  yarn add @xsolla/xui-image
9
17
  ```
10
18
 
11
- ## Usage
19
+ ## Demo
20
+
21
+ ### Basic Image
22
+
23
+ ```tsx
24
+ import * as React from 'react';
25
+ import { Image } from '@xsolla/xui-image';
26
+
27
+ export default function BasicImage() {
28
+ return (
29
+ <Image
30
+ src="https://example.com/photo.jpg"
31
+ alt="Sample photo"
32
+ />
33
+ );
34
+ }
35
+ ```
36
+
37
+ ### With Aspect Ratio
38
+
39
+ ```tsx
40
+ import * as React from 'react';
41
+ import { Image } from '@xsolla/xui-image';
42
+
43
+ export default function RatioImage() {
44
+ return (
45
+ <Image
46
+ src="https://example.com/photo.jpg"
47
+ alt="16:9 photo"
48
+ ratio="16:9"
49
+ width={400}
50
+ />
51
+ );
52
+ }
53
+ ```
54
+
55
+ ### With Border Radius
12
56
 
13
57
  ```tsx
58
+ import * as React from 'react';
59
+ import { Image } from '@xsolla/xui-image';
60
+
61
+ export default function RoundedImage() {
62
+ return (
63
+ <Image
64
+ src="https://example.com/photo.jpg"
65
+ alt="Rounded photo"
66
+ ratio="1:1"
67
+ width={200}
68
+ borderRadius={16}
69
+ />
70
+ );
71
+ }
72
+ ```
73
+
74
+ ### With Overlay Slot
75
+
76
+ ```tsx
77
+ import * as React from 'react';
78
+ import { Image } from '@xsolla/xui-image';
79
+
80
+ export default function OverlayImage() {
81
+ return (
82
+ <Image
83
+ src="https://example.com/photo.jpg"
84
+ alt="Photo with overlay"
85
+ ratio="16:9"
86
+ width={400}
87
+ slot={
88
+ <div style={{
89
+ background: 'rgba(0,0,0,0.5)',
90
+ color: 'white',
91
+ padding: 16,
92
+ width: '100%',
93
+ height: '100%',
94
+ display: 'flex',
95
+ alignItems: 'center',
96
+ justifyContent: 'center',
97
+ }}>
98
+ Overlay Content
99
+ </div>
100
+ }
101
+ />
102
+ );
103
+ }
104
+ ```
105
+
106
+ ## Anatomy
107
+
108
+ ```jsx
14
109
  import { Image } from '@xsolla/xui-image';
15
110
 
16
111
  <Image
17
- src="https://example.com/photo.jpg"
18
- alt="A landscape"
19
- ratio="16:9"
20
- borderRadius={8}
112
+ src="image-url.jpg" // Image source URL
113
+ alt="Description" // Alt text for accessibility
114
+ ratio="1:1" // Aspect ratio preset
115
+ customRatio="21 / 9" // Custom ratio (when ratio="Custom")
116
+ width={200} // Container width
117
+ borderRadius={0} // Border radius
118
+ slot={<Overlay />} // Overlay content
119
+ style={{}} // Container styles
120
+ imageStyle={{}} // Image element styles
21
121
  />
22
122
  ```
23
123
 
24
- ## Props
124
+ ## Examples
125
+
126
+ ### Aspect Ratio Gallery
127
+
128
+ ```tsx
129
+ import * as React from 'react';
130
+ import { Image } from '@xsolla/xui-image';
131
+
132
+ export default function RatioGallery() {
133
+ const src = "https://example.com/photo.jpg";
134
+
135
+ return (
136
+ <div style={{ display: 'flex', gap: 16, flexWrap: 'wrap' }}>
137
+ <div>
138
+ <p>1:1 (Square)</p>
139
+ <Image src={src} ratio="1:1" width={150} />
140
+ </div>
141
+ <div>
142
+ <p>16:9 (Widescreen)</p>
143
+ <Image src={src} ratio="16:9" width={200} />
144
+ </div>
145
+ <div>
146
+ <p>4:3 (Standard)</p>
147
+ <Image src={src} ratio="4:3" width={180} />
148
+ </div>
149
+ <div>
150
+ <p>3:2 (Photo)</p>
151
+ <Image src={src} ratio="3:2" width={180} />
152
+ </div>
153
+ <div>
154
+ <p>2:3 (Portrait)</p>
155
+ <Image src={src} ratio="2:3" width={120} />
156
+ </div>
157
+ <div>
158
+ <p>9:16 (Story)</p>
159
+ <Image src={src} ratio="9:16" width={100} />
160
+ </div>
161
+ </div>
162
+ );
163
+ }
164
+ ```
165
+
166
+ ### Custom Aspect Ratio
167
+
168
+ ```tsx
169
+ import * as React from 'react';
170
+ import { Image } from '@xsolla/xui-image';
171
+
172
+ export default function CustomRatioImage() {
173
+ return (
174
+ <Image
175
+ src="https://example.com/ultrawide.jpg"
176
+ alt="Ultra-wide photo"
177
+ ratio="Custom"
178
+ customRatio="21 / 9"
179
+ width={400}
180
+ />
181
+ );
182
+ }
183
+ ```
184
+
185
+ ### Placeholder State
186
+
187
+ ```tsx
188
+ import * as React from 'react';
189
+ import { Image } from '@xsolla/xui-image';
190
+
191
+ export default function PlaceholderImage() {
192
+ return (
193
+ <Image
194
+ ratio="16:9"
195
+ width={400}
196
+ slot={
197
+ <span style={{ color: '#999' }}>Loading...</span>
198
+ }
199
+ />
200
+ );
201
+ }
202
+ ```
203
+
204
+ ## API Reference
25
205
 
26
206
  ### Image
27
207
 
208
+ **Image Props:**
209
+
28
210
  | Prop | Type | Default | Description |
29
- |------|------|---------|-------------|
30
- | `src` | `string` | — | Image source URL |
31
- | `alt` | `string` | `""` | Image alt text |
32
- | `ratio` | `"1:1" \| "2:3" \| "3:2" \| "16:9" \| "4:3" \| "9:16" \| "Custom"` | `"1:1"` | Aspect ratio of the image |
33
- | `customRatio` | `string \| number` | — | Custom ratio when `ratio` is `"Custom"` (e.g. `"21 / 9"`) |
34
- | `slot` | `ReactNode` | — | Overlay or placeholder content rendered over the image |
35
- | `width` | `number \| string` | `"100%"` | Width of the image container |
36
- | `borderRadius` | `number \| string` | `0` | Border radius of the container |
211
+ | :--- | :--- | :------ | :---------- |
212
+ | src | `string` | - | Image source URL. |
213
+ | alt | `string` | `""` | Alt text for accessibility. |
214
+ | ratio | `ImageRatio` | `"1:1"` | Aspect ratio preset. |
215
+ | customRatio | `string \| number` | - | Custom ratio when ratio is "Custom". |
216
+ | width | `number \| string` | `"100%"` | Container width. |
217
+ | borderRadius | `number \| string` | `0` | Border radius of container. |
218
+ | slot | `ReactNode` | - | Overlay content (centered). |
219
+ | style | `CSSProperties` | - | Container styles. |
220
+ | imageStyle | `CSSProperties` | - | Image element styles. |
221
+
222
+ **ImageRatio Type:**
223
+
224
+ ```typescript
225
+ type ImageRatio =
226
+ | "1:1" // Square
227
+ | "2:3" // Portrait
228
+ | "3:2" // Landscape photo
229
+ | "16:9" // Widescreen
230
+ | "4:3" // Standard
231
+ | "9:16" // Story/mobile
232
+ | "Custom"; // Use customRatio
233
+ ```
234
+
235
+ ## Behavior
236
+
237
+ - Image fills container with `object-fit: cover`
238
+ - Background color shows when image hasn't loaded
239
+ - Slot content overlays the image (centered)
240
+ - Maintains aspect ratio regardless of source image dimensions
241
+
242
+ ## Accessibility
243
+
244
+ - Always provide meaningful `alt` text
245
+ - Decorative images can use `alt=""`
246
+ - Slot content should be accessible if interactive
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xsolla/xui-image",
3
- "version": "0.99.0",
3
+ "version": "0.100.0",
4
4
  "main": "./web/index.js",
5
5
  "module": "./web/index.mjs",
6
6
  "types": "./web/index.d.ts",
@@ -10,8 +10,8 @@
10
10
  "build:native": "PLATFORM=native tsup"
11
11
  },
12
12
  "dependencies": {
13
- "@xsolla/xui-core": "0.99.0",
14
- "@xsolla/xui-primitives-core": "0.99.0"
13
+ "@xsolla/xui-core": "0.100.0",
14
+ "@xsolla/xui-primitives-core": "0.100.0"
15
15
  },
16
16
  "peerDependencies": {
17
17
  "react": ">=16.8.0",