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