@fluentui/react-image 0.0.0-nightly-20220302-0405.1
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/CHANGELOG.json +3258 -0
- package/CHANGELOG.md +1240 -0
- package/LICENSE +15 -0
- package/MIGRATION.md +235 -0
- package/README.md +57 -0
- package/Spec.md +173 -0
- package/dist/react-image.d.ts +60 -0
- package/lib/Image.d.ts +1 -0
- package/lib/Image.js +2 -0
- package/lib/Image.js.map +1 -0
- package/lib/components/Image/Image.d.ts +6 -0
- package/lib/components/Image/Image.js +15 -0
- package/lib/components/Image/Image.js.map +1 -0
- package/lib/components/Image/Image.types.d.ts +30 -0
- package/lib/components/Image/Image.types.js +2 -0
- package/lib/components/Image/Image.types.js.map +1 -0
- package/lib/components/Image/index.d.ts +5 -0
- package/lib/components/Image/index.js +6 -0
- package/lib/components/Image/index.js.map +1 -0
- package/lib/components/Image/renderImage.d.ts +6 -0
- package/lib/components/Image/renderImage.js +16 -0
- package/lib/components/Image/renderImage.js.map +1 -0
- package/lib/components/Image/useImage.d.ts +6 -0
- package/lib/components/Image/useImage.js +30 -0
- package/lib/components/Image/useImage.js.map +1 -0
- package/lib/components/Image/useImageStyles.d.ts +3 -0
- package/lib/components/Image/useImageStyles.js +78 -0
- package/lib/components/Image/useImageStyles.js.map +1 -0
- package/lib/index.d.ts +1 -0
- package/lib/index.js +2 -0
- package/lib/index.js.map +1 -0
- package/lib/tsdoc-metadata.json +11 -0
- package/lib-commonjs/Image.d.ts +1 -0
- package/lib-commonjs/Image.js +10 -0
- package/lib-commonjs/Image.js.map +1 -0
- package/lib-commonjs/components/Image/Image.d.ts +6 -0
- package/lib-commonjs/components/Image/Image.js +26 -0
- package/lib-commonjs/components/Image/Image.js.map +1 -0
- package/lib-commonjs/components/Image/Image.types.d.ts +30 -0
- package/lib-commonjs/components/Image/Image.types.js +6 -0
- package/lib-commonjs/components/Image/Image.types.js.map +1 -0
- package/lib-commonjs/components/Image/index.d.ts +5 -0
- package/lib-commonjs/components/Image/index.js +18 -0
- package/lib-commonjs/components/Image/index.js.map +1 -0
- package/lib-commonjs/components/Image/renderImage.d.ts +6 -0
- package/lib-commonjs/components/Image/renderImage.js +27 -0
- package/lib-commonjs/components/Image/renderImage.js.map +1 -0
- package/lib-commonjs/components/Image/useImage.d.ts +6 -0
- package/lib-commonjs/components/Image/useImage.js +40 -0
- package/lib-commonjs/components/Image/useImage.js.map +1 -0
- package/lib-commonjs/components/Image/useImageStyles.d.ts +3 -0
- package/lib-commonjs/components/Image/useImageStyles.js +89 -0
- package/lib-commonjs/components/Image/useImageStyles.js.map +1 -0
- package/lib-commonjs/index.d.ts +1 -0
- package/lib-commonjs/index.js +10 -0
- package/lib-commonjs/index.js.map +1 -0
- package/package.json +64 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
@fluentui/react-image
|
|
2
|
+
|
|
3
|
+
Copyright (c) Microsoft Corporation
|
|
4
|
+
|
|
5
|
+
All rights reserved.
|
|
6
|
+
|
|
7
|
+
MIT License
|
|
8
|
+
|
|
9
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ""Software""), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
10
|
+
|
|
11
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
12
|
+
|
|
13
|
+
THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
14
|
+
|
|
15
|
+
Note: Usage of the fonts and icons referenced in Fluent UI React is subject to the terms listed at https://aka.ms/fluentui-assets-license
|
package/MIGRATION.md
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
# Image Migration
|
|
2
|
+
|
|
3
|
+
## Introduction
|
|
4
|
+
|
|
5
|
+
This guide is a reference for upgrading the Image component from v8 (Fabric) or v0 (Northstar) to v9 (FluentUI vNext).
|
|
6
|
+
|
|
7
|
+
## Migration from v8 (Fabric)
|
|
8
|
+
|
|
9
|
+
### Property mapping
|
|
10
|
+
|
|
11
|
+
The table below presents a mapping of props between the v8 (FabricUI) and v9 (Fluent UI vNext) in order to clarify which properties require changes to achieve the same result.
|
|
12
|
+
|
|
13
|
+
> ⚠️ Note - Properties not in this table are considered deprecated.
|
|
14
|
+
|
|
15
|
+
| v7 / v8 | v9 | Good to go? |
|
|
16
|
+
| ----------------------- | ------- | ----------- |
|
|
17
|
+
| `className` | - | ✔️ |
|
|
18
|
+
| `coverStyle` | `fit` | ⚠️ |
|
|
19
|
+
| `imageFit` | `fit` | ✔️ |
|
|
20
|
+
| `maximizeFrame` | `block` | ✔️ |
|
|
21
|
+
| `loading` | - | ✔️ |
|
|
22
|
+
| `onLoadingStateChanged` | - | ❌ |
|
|
23
|
+
| `shouldFadeIn` | - | ❌ |
|
|
24
|
+
| `shouldStartVisible` | - | ❌ |
|
|
25
|
+
| `styles` | - | ❌ |
|
|
26
|
+
| `theme` | - | ❓ |
|
|
27
|
+
|
|
28
|
+
### className
|
|
29
|
+
|
|
30
|
+
_This property has not changed and can be left as is._
|
|
31
|
+
|
|
32
|
+
### coverStyle
|
|
33
|
+
|
|
34
|
+
The behaviour of this prop can be achieved using the `fit` prop with the value of `cover`.
|
|
35
|
+
|
|
36
|
+
```jsx
|
|
37
|
+
<Image src="example.jpg" fit="cover" />
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### imageFit
|
|
41
|
+
|
|
42
|
+
This can be achieved using the `fit` prop by asigning the value of `contain`.
|
|
43
|
+
|
|
44
|
+
```jsx
|
|
45
|
+
<Image src="example.jpg" fit="contain" />
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### maximizeFrame
|
|
49
|
+
|
|
50
|
+
This prop has been renamed to `block` which will result in the same behaviour as before.
|
|
51
|
+
|
|
52
|
+
```jsx
|
|
53
|
+
<Image src="example.jpg" block />
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### loading
|
|
57
|
+
|
|
58
|
+
_This property has not changed and can be used as is._
|
|
59
|
+
|
|
60
|
+
### onLoadingStateChanged
|
|
61
|
+
|
|
62
|
+
For v9, this feature is no longer supported. The alternative would be to use the global events such as: `onLoad`, `onError` to detect the image loading state.
|
|
63
|
+
|
|
64
|
+
### shouldFadeIn
|
|
65
|
+
|
|
66
|
+
For v9, this feature is no longer supported. The alternative is to apply the animation through `make-styles` and using the global event `onLoad`. Below is an example of a migration:
|
|
67
|
+
|
|
68
|
+
```jsx
|
|
69
|
+
import { useState } from 'react';
|
|
70
|
+
import { Image } from '@fluentui/react-image';
|
|
71
|
+
import { makeStyles } from '@griffel/react';
|
|
72
|
+
|
|
73
|
+
const useStyles = makeStyles(theme => ({
|
|
74
|
+
fadeIn400: {
|
|
75
|
+
animationName: {
|
|
76
|
+
from : {
|
|
77
|
+
opacity: 0,
|
|
78
|
+
},
|
|
79
|
+
to: {
|
|
80
|
+
opacity: 1,
|
|
81
|
+
}
|
|
82
|
+
},
|
|
83
|
+
animationIterationCount: 'infinite',
|
|
84
|
+
animationDuration: '0.367s',
|
|
85
|
+
},
|
|
86
|
+
})
|
|
87
|
+
|
|
88
|
+
const MyComponent = () => {
|
|
89
|
+
const [isLoaded, setLoaded] = useState(false);
|
|
90
|
+
const styles = useStyles()
|
|
91
|
+
|
|
92
|
+
return <Image src="example.jpg" onLoad={()=> setLoaded(true)} className={!isLoaded? styles.fadeIn400 : ''} />
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### shouldStartVisible
|
|
97
|
+
|
|
98
|
+
For v9, this feature is no longer supported. The alternative would be to use the global events such as: `onLoad` and `onError` to achieve the same behaviour. Below is an example showcasing this:
|
|
99
|
+
|
|
100
|
+
```jsx
|
|
101
|
+
import { useState } from 'react';
|
|
102
|
+
import { makeStyles } from '@griffel/react';
|
|
103
|
+
import { Image } from '@fluentui/react-image';
|
|
104
|
+
|
|
105
|
+
const useStyles = makeStyles({
|
|
106
|
+
root: {
|
|
107
|
+
display: 'none',
|
|
108
|
+
},
|
|
109
|
+
});
|
|
110
|
+
|
|
111
|
+
export default function App() {
|
|
112
|
+
const [isLoaded, setLoaded] = useState(null);
|
|
113
|
+
|
|
114
|
+
const styles = useStyles();
|
|
115
|
+
|
|
116
|
+
return (
|
|
117
|
+
<Image
|
|
118
|
+
src="https://via.placeholder.com/300x300"
|
|
119
|
+
alt="Example image"
|
|
120
|
+
onLoad={() => setLoaded(true)}
|
|
121
|
+
onError={() => setLoaded(false)}
|
|
122
|
+
className={isLoaded === false ? styles.root : ''}
|
|
123
|
+
/>
|
|
124
|
+
);
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### styles
|
|
129
|
+
|
|
130
|
+
_This property has not changed and can be used as is. However, we highly recommend that you migrate to a `make-styles` styling solution for performance reasons._
|
|
131
|
+
|
|
132
|
+
### theme
|
|
133
|
+
|
|
134
|
+
_This property has not changed and can be used as is. However, we highly recommend that you migrate to a `make-styles` styling solution for performance reasons._
|
|
135
|
+
|
|
136
|
+
## Migration from v0 (Northstar)
|
|
137
|
+
|
|
138
|
+
### Property mapping
|
|
139
|
+
|
|
140
|
+
The table below presents a mapping of props between the v0 and v9 versions in order to make it clear which properties require changes to achieve the same result.
|
|
141
|
+
|
|
142
|
+
| v0 | v9 | Good to go? |
|
|
143
|
+
| --------------- | ------------------ | ----------- |
|
|
144
|
+
| `accessibility` | - | ❌ |
|
|
145
|
+
| `alt` | - | ✔️ |
|
|
146
|
+
| `aria-label` | - | ✔️ |
|
|
147
|
+
| `as` | - | ❌ |
|
|
148
|
+
| `avatar` | `shape="circular"` | ✔️ |
|
|
149
|
+
| `circular` | `shape="circular"` | ✔️ |
|
|
150
|
+
| `className` | - | ✔️ |
|
|
151
|
+
| `fluid` | `block` | ✔️ |
|
|
152
|
+
| `styles` | - | ❌ |
|
|
153
|
+
| `variables` | - | ❌ |
|
|
154
|
+
|
|
155
|
+
### accessibility
|
|
156
|
+
|
|
157
|
+
For v9, this property is no longer supported. It is recommended to follow the best practices of a11y in order for Image to be accessible to assistive tools. Thus:
|
|
158
|
+
|
|
159
|
+
- It is important for Image to have the `alt` description.
|
|
160
|
+
- In case the Image is decorative only, have either `role="presentation"` or `aria-hidden`. Ensure the correct usage of these two attributes, based on your objectives.
|
|
161
|
+
|
|
162
|
+
### alt
|
|
163
|
+
|
|
164
|
+
_This property has not changed and can be left as is._
|
|
165
|
+
|
|
166
|
+
### aria-label
|
|
167
|
+
|
|
168
|
+
_This property has not changed and can be left as is._
|
|
169
|
+
|
|
170
|
+
### as
|
|
171
|
+
|
|
172
|
+
For v9, this property is no longer supported. The Image prop will always be an `<img/>` element, it is not possible to show an image as any other element.
|
|
173
|
+
|
|
174
|
+
### avatar
|
|
175
|
+
|
|
176
|
+
This can be achieved using the `shape` prop with the value of `circular`.
|
|
177
|
+
|
|
178
|
+
```jsx
|
|
179
|
+
<Image src="example.jpg" shape="circular" />
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### circular
|
|
183
|
+
|
|
184
|
+
This can be achieved using the `shape` prop with the value of `circular`.
|
|
185
|
+
|
|
186
|
+
```jsx
|
|
187
|
+
<Image src="example.jpg" shape="circular" />
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### className
|
|
191
|
+
|
|
192
|
+
_This property has not changed and can be left as is._
|
|
193
|
+
|
|
194
|
+
### fluid
|
|
195
|
+
|
|
196
|
+
This prop has been renamed to `block` which will result into the same behaviour as before.
|
|
197
|
+
|
|
198
|
+
```jsx
|
|
199
|
+
<Image src="example.jpg" block />
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### styles
|
|
203
|
+
|
|
204
|
+
_This property has not changed and can be used as is. However, we highly recommend that you migrate to a `make-styles` styling solution for performance reasons._
|
|
205
|
+
|
|
206
|
+
### variables
|
|
207
|
+
|
|
208
|
+
For v9, this feature is no longer supported. The alternative is to apply styles through `make-styles`. Below is an example of a migration:
|
|
209
|
+
|
|
210
|
+
#### v0 (Northstar) implementation
|
|
211
|
+
|
|
212
|
+
```jsx
|
|
213
|
+
const MyComponent = () => {
|
|
214
|
+
return <Image src="example.jpg" variables={{ width: '100px' }} />;
|
|
215
|
+
};
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
#### v9 (Fluent UI vNext) implementation
|
|
219
|
+
|
|
220
|
+
```jsx
|
|
221
|
+
import { Image } from '@fluentui/react-image';
|
|
222
|
+
import { makeStyles } from '@griffel/react';
|
|
223
|
+
|
|
224
|
+
const useStyles = makeStyles(theme => ({
|
|
225
|
+
width100: {
|
|
226
|
+
width: '100px'
|
|
227
|
+
},
|
|
228
|
+
})
|
|
229
|
+
|
|
230
|
+
const MyComponent = () => {
|
|
231
|
+
const styles = useStyles()
|
|
232
|
+
|
|
233
|
+
return <Image src="example.jpg" className={styles.width100} />
|
|
234
|
+
}
|
|
235
|
+
```
|
package/README.md
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# @fluentui/react-image
|
|
2
|
+
|
|
3
|
+
**React Image component for [Fluent UI React](https://developer.microsoft.com/en-us/fluentui)**
|
|
4
|
+
|
|
5
|
+
> WIP 🚧 - These are not production-ready components as we are still in a Beta phase.
|
|
6
|
+
|
|
7
|
+
Usage of Image component ensures consistent styling and behaviour of images in your application based on the Fluent UI Design System.
|
|
8
|
+
|
|
9
|
+
## Usage
|
|
10
|
+
|
|
11
|
+
To use the Image component, it is required to install the main package of Fluent UI components:
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npm install @fluentui/react-components
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
```js
|
|
18
|
+
import { Image } from '@fluentui/react-components';
|
|
19
|
+
|
|
20
|
+
const App = () => {
|
|
21
|
+
return <Image src="example_image.png" />;
|
|
22
|
+
};
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Or, installing only the `react-image` package:
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
npm install @fluentui/react-image
|
|
29
|
+
npm install @fluentui/react-provider
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
```js
|
|
33
|
+
import { Image } from '@fluentui/react-image';
|
|
34
|
+
import { FluentProvider } from '@fluentui/react-provider';
|
|
35
|
+
|
|
36
|
+
const App = () => (
|
|
37
|
+
<FluentProvider>
|
|
38
|
+
<Image src="example_image.png" alt="Example image" />;
|
|
39
|
+
</FluentProvider>
|
|
40
|
+
);
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The DOM structure will result into:
|
|
44
|
+
|
|
45
|
+
```jsx
|
|
46
|
+
<img src="example_image.png" alt="Example image" />
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## API
|
|
50
|
+
|
|
51
|
+
Image component is build upon the `<img/>` tag, which does support all the native attributes. Additionaly, the following properties are available: `bordered`, `fit`, `block`, `shape` and `shadow`.
|
|
52
|
+
|
|
53
|
+
For more information on the component, please refer to the [API documentation](https://aka.ms/fluentui-storybook).
|
|
54
|
+
|
|
55
|
+
## Migration
|
|
56
|
+
|
|
57
|
+
For migrating from older versions of FluentUI, please check out the [migration guide](./MIGRATION.md)
|
package/Spec.md
ADDED
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# @fluentui/react-image
|
|
2
|
+
|
|
3
|
+
## Background
|
|
4
|
+
|
|
5
|
+
Image is a visual representation of some content, such as a photo, illustration etc.
|
|
6
|
+
|
|
7
|
+
## Concerns
|
|
8
|
+
|
|
9
|
+
Based on the OpenUI research and the Figma specification, Image seems to be one of those components that is purely styling, thus I would appreciate your answers in any of these questions:
|
|
10
|
+
|
|
11
|
+
- Are there any components would need to use Image?
|
|
12
|
+
- Apart from styling, are there any other functionalities for Image?
|
|
13
|
+
|
|
14
|
+
**Conclusion**: Some potential features that Image can have are:
|
|
15
|
+
|
|
16
|
+
- fallback image placeholder when image fails to load
|
|
17
|
+
- onLoading callback when image fails to load
|
|
18
|
+
- styling helpers
|
|
19
|
+
These will be addressed on later iterations when needed
|
|
20
|
+
|
|
21
|
+
- Is there any benefit of having Image as a component? (taking into consideration that it is css styling and we will need to maintain it over time.)
|
|
22
|
+
|
|
23
|
+
**Conclusion**: The image component will ensure correct styling and behaviour regardless of the Theme
|
|
24
|
+
|
|
25
|
+
## Prior Art
|
|
26
|
+
|
|
27
|
+
- Convergence epic issue: [#16658](https://github.com/microsoft/fluentui/issues/16658)
|
|
28
|
+
- Open UI research [Link](https://open-ui.org/components/image.research), PR: [#274](https://github.com/openui/open-ui/pull/274)
|
|
29
|
+
|
|
30
|
+
### V8/v0 comparison
|
|
31
|
+
|
|
32
|
+
Comparison done in: [#17608](https://github.com/microsoft/fluentui/pull/17608)
|
|
33
|
+
|
|
34
|
+
[image@v7/v8]: https://developer.microsoft.com/en-us/fluentui#/controls/web/image
|
|
35
|
+
[image@v0]: https://fluentsite.z22.web.core.windows.net/0.53.0/components/image/props
|
|
36
|
+
|
|
37
|
+
| Purpose | v7 / v8 | v0 | Matching |
|
|
38
|
+
| ----------------------------------------------------------------------- | ----------------------- | --------------- | ----------------------------- |
|
|
39
|
+
| Additional CSS class name(s) to apply | `className` | `className` | matching |
|
|
40
|
+
| Specifies the cover style to be used for this image | `coverStyle` | N/A | v0 missing |
|
|
41
|
+
| Replaces the src in case of errors | `errorSrc` [DEPRECATED] | N/A | _See `onLoadingStateChanged`_ |
|
|
42
|
+
| Determines how the image is scaled and cropped to fit the frame | `imageFit` | `fluid` | partially matching |
|
|
43
|
+
| Expands image frame to fill its parent container | `maximizeFrame` | `fluid` | partially matching |
|
|
44
|
+
| Optional callback for when the image load state changed | `onLoadingStateChanged` | N/A | v0 missing |
|
|
45
|
+
| Fades the image in when loaded | `shouldFadeIn` | N/A | v0 missing |
|
|
46
|
+
| The image starts as visible and is hidden on error | `shouldStartVisible` | N/A | v0 missing |
|
|
47
|
+
| Provides customized styling that will layer on top of the variant rules | `styles` | `styles` | matching |
|
|
48
|
+
| Theme provided by HOC | `theme` | `variables` | matching |
|
|
49
|
+
| Accessibility behavior overridden by the user | N/A | `accessibility` | v7/v8 missing |
|
|
50
|
+
| An element type to render as (string or component) | N/A | `as` | v7/v8 missing |
|
|
51
|
+
| An image may be formatted to appear inline with text as an avatar | N/A | `avatar` | v7/v8 missing |
|
|
52
|
+
| An image can appear circular | N/A | `circular` | v7/v8 missing |
|
|
53
|
+
| Component design prop | N/A | `design` | v7/v8 missing |
|
|
54
|
+
| Image source URL | N/A | `src` | v7/v8 missing |
|
|
55
|
+
|
|
56
|
+
### v8 usage
|
|
57
|
+
|
|
58
|
+
```jsx
|
|
59
|
+
import { Image, ImageFit } from '@fluentui/react/lib/Image';
|
|
60
|
+
|
|
61
|
+
<Image maximizeFrame imageFit={ImageFit.contain} src="..." alt="Example of the image component in v8" />;
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### v0 usage
|
|
65
|
+
|
|
66
|
+
```jsx
|
|
67
|
+
<Image block src="..." alt="Example of the image component in v0" />
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Variants
|
|
71
|
+
|
|
72
|
+
n/a
|
|
73
|
+
|
|
74
|
+
## API proposal
|
|
75
|
+
|
|
76
|
+
See [react-image/Image.types.ts] for the API.
|
|
77
|
+
|
|
78
|
+
[react-image/image.types.ts]: https://github.com/microsoft/fluentui/blob/master/packages/react-image/src/components/Image/Image.types.ts
|
|
79
|
+
|
|
80
|
+
Proposed component props:
|
|
81
|
+
|
|
82
|
+
| Name | Type | Default value | Comments |
|
|
83
|
+
| ---------- | --------- | ------------- | -------------------------------------------- |
|
|
84
|
+
| `bordered` | `boolean` | `false` | |
|
|
85
|
+
| `fit` | `string` | "`none`" | One of: `none`, `center`, `contain`, `cover` |
|
|
86
|
+
| `block` | `boolean` | `false` | |
|
|
87
|
+
| `shape ` | `string ` | `false` | One of: `square`, `circular` , `rounded` |
|
|
88
|
+
| `shadow` | `boolean` | `false` | |
|
|
89
|
+
|
|
90
|
+
All native html attributes of the `<img />` will be available to be used as props of the Image component.
|
|
91
|
+
|
|
92
|
+
## Sample Code
|
|
93
|
+
|
|
94
|
+
Sample code based on the proposed API:
|
|
95
|
+
|
|
96
|
+
### Bordered
|
|
97
|
+
|
|
98
|
+
```jsx
|
|
99
|
+
<Image bordered src="..." />
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Block
|
|
103
|
+
|
|
104
|
+
```jsx
|
|
105
|
+
<Image block src="..." />
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Rounded
|
|
109
|
+
|
|
110
|
+
```jsx
|
|
111
|
+
<Image shape="rounded" src="..." />
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Circular
|
|
115
|
+
|
|
116
|
+
```jsx
|
|
117
|
+
<Image shape="circular" src="..." />
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Fit
|
|
121
|
+
|
|
122
|
+
```jsx
|
|
123
|
+
// None
|
|
124
|
+
<Image fit="none" src="..." />
|
|
125
|
+
|
|
126
|
+
// Center
|
|
127
|
+
<Image fit="center" src="..." />
|
|
128
|
+
|
|
129
|
+
// Contain
|
|
130
|
+
<Image fit="contain" src="..." />
|
|
131
|
+
|
|
132
|
+
// Cover
|
|
133
|
+
<Image fit="cover" src="..." />
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Structure
|
|
137
|
+
|
|
138
|
+
### Public
|
|
139
|
+
|
|
140
|
+
```tsx
|
|
141
|
+
<Image src=".." />
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Internal
|
|
145
|
+
|
|
146
|
+
```tsx
|
|
147
|
+
<slots.root {...slotProps.root} />
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### DOM
|
|
151
|
+
|
|
152
|
+
```tsx
|
|
153
|
+
<img src="..." class="...">
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
<!-- ## Migration -->
|
|
157
|
+
|
|
158
|
+
<!-- _Describe what will need to be done to upgrade from the existing implementations:_
|
|
159
|
+
|
|
160
|
+
- _Migration from v8_
|
|
161
|
+
- _Migration from v0_ -->
|
|
162
|
+
|
|
163
|
+
## Accessibility
|
|
164
|
+
|
|
165
|
+
Images should include the `alt` attribute that includes a description of the image's content and function to be accessible to assistive technologies. The alt description should be concise and clearly communicate the meaning and purpose of the image on where it was included. Avoid using "image of", "picture of" etc. as it is redundant.
|
|
166
|
+
|
|
167
|
+
The images that are only decorative and do not have the structural relevance implied by the semantic element should use the `alt=""` (null alt text) or `role="presentation"`/`role="none"` which will remove the semantic meaning of the element. In case the image is needed to be removed from the accessibility tree then `aria-hidden="true"` can be used.
|
|
168
|
+
|
|
169
|
+
### Relevant documents
|
|
170
|
+
|
|
171
|
+
- [WAI-ARIA 1.1 img Spec](https://www.w3.org/TR/wai-aria-1.1/#img)
|
|
172
|
+
- [WAI-ARIA 1.2 img Spec](https://www.w3.org/TR/wai-aria-1.2/#img)
|
|
173
|
+
- [WAI-ARIA 1.1 Hiding Semantics](https://www.w3.org/TR/wai-aria-practices-1.1/#presentation_role)
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import type { ComponentProps } from '@fluentui/react-utilities';
|
|
2
|
+
import type { ComponentState } from '@fluentui/react-utilities';
|
|
3
|
+
import type { ForwardRefComponent } from '@fluentui/react-utilities';
|
|
4
|
+
import * as React_2 from 'react';
|
|
5
|
+
import type { Slot } from '@fluentui/react-utilities';
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* The Image component ensures the consistent styling of images.
|
|
9
|
+
*/
|
|
10
|
+
declare const Image_2: ForwardRefComponent<ImageProps>;
|
|
11
|
+
export { Image_2 as Image }
|
|
12
|
+
|
|
13
|
+
export declare const imageClassName = "fui-Image";
|
|
14
|
+
|
|
15
|
+
declare type ImageCommons = {
|
|
16
|
+
/**
|
|
17
|
+
* An image can appear with rectangular border.
|
|
18
|
+
*/
|
|
19
|
+
bordered?: boolean;
|
|
20
|
+
/**
|
|
21
|
+
* An image can set how it should be resized to fit its container.
|
|
22
|
+
*/
|
|
23
|
+
fit?: 'none' | 'center' | 'contain' | 'cover';
|
|
24
|
+
/**
|
|
25
|
+
* An image can take up the width of its container.
|
|
26
|
+
*/
|
|
27
|
+
block?: boolean;
|
|
28
|
+
/**
|
|
29
|
+
* An image can appear square, circular, or rounded.
|
|
30
|
+
* @defaultvalue square
|
|
31
|
+
*/
|
|
32
|
+
shape?: 'square' | 'circular' | 'rounded';
|
|
33
|
+
/**
|
|
34
|
+
* An image can appear elevated with shadow.
|
|
35
|
+
*/
|
|
36
|
+
shadow?: boolean;
|
|
37
|
+
};
|
|
38
|
+
|
|
39
|
+
export declare type ImageProps = ComponentProps<ImageSlots> & Partial<ImageCommons>;
|
|
40
|
+
|
|
41
|
+
export declare type ImageSlots = {
|
|
42
|
+
root: Slot<'img'>;
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
export declare type ImageState = ComponentState<ImageSlots> & ImageCommons;
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Define the render function.
|
|
49
|
+
* Given the state of an image, renders it.
|
|
50
|
+
*/
|
|
51
|
+
export declare const renderImage_unstable: (state: ImageState) => JSX.Element;
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Given user props, returns state and render function for an Image.
|
|
55
|
+
*/
|
|
56
|
+
export declare const useImage_unstable: (props: ImageProps, ref: React_2.Ref<HTMLImageElement>) => ImageState;
|
|
57
|
+
|
|
58
|
+
export declare const useImageStyles_unstable: (state: ImageState) => void;
|
|
59
|
+
|
|
60
|
+
export { }
|
package/lib/Image.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from './components/Image/index';
|
package/lib/Image.js
ADDED
package/lib/Image.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"Image.js","sourceRoot":"../src/","sources":["Image.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC","sourcesContent":["export * from './components/Image/index';\n"]}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import * as React from 'react';
|
|
2
|
+
import { renderImage_unstable } from './renderImage';
|
|
3
|
+
import { useImage_unstable } from './useImage';
|
|
4
|
+
import { useImageStyles_unstable } from './useImageStyles';
|
|
5
|
+
/**
|
|
6
|
+
* The Image component ensures the consistent styling of images.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
export const Image = /*#__PURE__*/React.forwardRef((props, ref) => {
|
|
10
|
+
const state = useImage_unstable(props, ref);
|
|
11
|
+
useImageStyles_unstable(state);
|
|
12
|
+
return renderImage_unstable(state);
|
|
13
|
+
});
|
|
14
|
+
Image.displayName = 'Image';
|
|
15
|
+
//# sourceMappingURL=Image.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["components/Image/Image.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAZ,MAAuB,OAAvB;AACA,SAAS,oBAAT,QAAqC,eAArC;AACA,SAAS,iBAAT,QAAkC,YAAlC;AACA,SAAS,uBAAT,QAAwC,kBAAxC;AAIA;;AAEG;;AACH,OAAO,MAAM,KAAK,gBAAoC,KAAK,CAAC,UAAN,CAAiB,CAAC,KAAD,EAAQ,GAAR,KAAe;AACpF,QAAM,KAAK,GAAG,iBAAiB,CAAC,KAAD,EAAQ,GAAR,CAA/B;AACA,EAAA,uBAAuB,CAAC,KAAD,CAAvB;AAEA,SAAO,oBAAoB,CAAC,KAAD,CAA3B;AACD,CALqD,CAA/C;AAOP,KAAK,CAAC,WAAN,GAAoB,OAApB","sourcesContent":["import * as React from 'react';\nimport { renderImage_unstable } from './renderImage';\nimport { useImage_unstable } from './useImage';\nimport { useImageStyles_unstable } from './useImageStyles';\nimport type { ImageProps } from './Image.types';\nimport type { ForwardRefComponent } from '@fluentui/react-utilities';\n\n/**\n * The Image component ensures the consistent styling of images.\n */\nexport const Image: ForwardRefComponent<ImageProps> = React.forwardRef((props, ref) => {\n const state = useImage_unstable(props, ref);\n useImageStyles_unstable(state);\n\n return renderImage_unstable(state);\n});\n\nImage.displayName = 'Image';\n"],"sourceRoot":"../src/"}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import type { ComponentState, ComponentProps, Slot } from '@fluentui/react-utilities';
|
|
2
|
+
export declare type ImageSlots = {
|
|
3
|
+
root: Slot<'img'>;
|
|
4
|
+
};
|
|
5
|
+
declare type ImageCommons = {
|
|
6
|
+
/**
|
|
7
|
+
* An image can appear with rectangular border.
|
|
8
|
+
*/
|
|
9
|
+
bordered?: boolean;
|
|
10
|
+
/**
|
|
11
|
+
* An image can set how it should be resized to fit its container.
|
|
12
|
+
*/
|
|
13
|
+
fit?: 'none' | 'center' | 'contain' | 'cover';
|
|
14
|
+
/**
|
|
15
|
+
* An image can take up the width of its container.
|
|
16
|
+
*/
|
|
17
|
+
block?: boolean;
|
|
18
|
+
/**
|
|
19
|
+
* An image can appear square, circular, or rounded.
|
|
20
|
+
* @defaultvalue square
|
|
21
|
+
*/
|
|
22
|
+
shape?: 'square' | 'circular' | 'rounded';
|
|
23
|
+
/**
|
|
24
|
+
* An image can appear elevated with shadow.
|
|
25
|
+
*/
|
|
26
|
+
shadow?: boolean;
|
|
27
|
+
};
|
|
28
|
+
export declare type ImageProps = ComponentProps<ImageSlots> & Partial<ImageCommons>;
|
|
29
|
+
export declare type ImageState = ComponentState<ImageSlots> & ImageCommons;
|
|
30
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"Image.types.js","sourceRoot":"../src/","sources":["components/Image/Image.types.ts"],"names":[],"mappings":"","sourcesContent":["import type { ComponentState, ComponentProps, Slot } from '@fluentui/react-utilities';\n\nexport type ImageSlots = {\n root: Slot<'img'>;\n};\n\ntype ImageCommons = {\n /**\n * An image can appear with rectangular border.\n */\n bordered?: boolean;\n\n /**\n * An image can set how it should be resized to fit its container.\n */\n fit?: 'none' | 'center' | 'contain' | 'cover';\n\n /**\n * An image can take up the width of its container.\n */\n block?: boolean;\n\n /**\n * An image can appear square, circular, or rounded.\n * @defaultvalue square\n */\n shape?: 'square' | 'circular' | 'rounded';\n\n /**\n * An image can appear elevated with shadow.\n */\n shadow?: boolean;\n};\n\nexport type ImageProps = ComponentProps<ImageSlots> & Partial<ImageCommons>;\n\nexport type ImageState = ComponentState<ImageSlots> & ImageCommons;\n"]}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"../src/","sources":["components/Image/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC","sourcesContent":["export * from './Image.types';\nexport * from './Image';\nexport * from './renderImage';\nexport * from './useImage';\nexport * from './useImageStyles';\n"]}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import * as React from 'react';
|
|
2
|
+
import { getSlots } from '@fluentui/react-utilities';
|
|
3
|
+
/**
|
|
4
|
+
* Define the render function.
|
|
5
|
+
* Given the state of an image, renders it.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
export const renderImage_unstable = state => {
|
|
9
|
+
const {
|
|
10
|
+
slots,
|
|
11
|
+
slotProps
|
|
12
|
+
} = getSlots(state);
|
|
13
|
+
return /*#__PURE__*/React.createElement(slots.root, { ...slotProps.root
|
|
14
|
+
});
|
|
15
|
+
};
|
|
16
|
+
//# sourceMappingURL=renderImage.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["components/Image/renderImage.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAZ,MAAuB,OAAvB;AACA,SAAS,QAAT,QAAyB,2BAAzB;AAGA;;;AAGG;;AACH,OAAO,MAAM,oBAAoB,GAAI,KAAD,IAAsB;AACxD,QAAM;AAAE,IAAA,KAAF;AAAS,IAAA;AAAT,MAAuB,QAAQ,CAAa,KAAb,CAArC;AAEA,sBAAO,KAAA,CAAA,aAAA,CAAC,KAAK,CAAC,IAAP,EAAW,EAAA,GAAK,SAAS,CAAC;AAAf,GAAX,CAAP;AACD,CAJM","sourcesContent":["import * as React from 'react';\nimport { getSlots } from '@fluentui/react-utilities';\nimport { ImageSlots, ImageState } from './Image.types';\n\n/**\n * Define the render function.\n * Given the state of an image, renders it.\n */\nexport const renderImage_unstable = (state: ImageState) => {\n const { slots, slotProps } = getSlots<ImageSlots>(state);\n\n return <slots.root {...slotProps.root} />;\n};\n"],"sourceRoot":"../src/"}
|