import { Meta, Story, Preview } from '@storybook/addon-docs/blocks';
import * as Stories from './examples';

<Meta title="Components|Image" />

# Image

An accessible and responsive image component.

## Props

| Name                      | Type      | Default |
| ------------------------- | --------- | ------- |
| ...ViewProps              | | |
| blurRadius                | ?number   | |
| defaultSource             | ?Source   | |
| draggable                 | ?boolean  | false |
| onError                   | ?Function | |
| onLoad                    | ?Function | false |
| onLoadEnd                 | ?Function | false |
| onLoadStart               | ?Function | false |
| resizeMode                | ?ResizeMode | 'cover' |
| source                    | Source    | false |
| style                     | ?Style    | |

### blurRadius

The blur radius of the blur filter added to the image.

### defaultSource

The source `uri` is a string representing a placeholder to display while the main image is being loaded.

```js
type Source = { uri: string, width: number, height: number }
```

<Preview withSource='none'>
  <Story name="defaultSource">
    <Stories.defaultSource />
  </Story>
</Preview>

### draggable

This is a web-only prop that indicates whether the image can be dragged with
native browser behavior. The default is `false`.

<Preview withSource='none'>
  <Story name="draggable">
    <Stories.draggable />
  </Story>
</Preview>

### onError

Called on load error with ``{nativeEvent: {error}}``.

<Preview withSource='none'>
  <Story name="onError">
    <Stories.onError />
  </Story>
</Preview>

### onLoad

Called when load completes successfully.

<Preview withSource='none'>
  <Story name="onLoad">
    <Stories.onLoad />
  </Story>
</Preview>

### resizeMode

Determines how to resize the image when the frame doesn't match the raw image dimensions.

```js
type ResizeMode = 'center' | 'contain' | 'cover' | 'none' | 'repeat' | 'stretch';
```

<Preview withSource='none'>
  <Story name="resizeMode">
    <Stories.resizeMode />
  </Story>
</Preview>

### source

The source `uri` is a string representing the resource identifier for the image, which could be an http address or a base64 encoded image.

```js
type Source = { uri: string, width: number, height: number }
```

<Preview withSource='none'>
  <Story name="source">
    <Stories.source />
  </Story>
</Preview>

### style

```js
{
  ...ViewProps.style
  resizeMode: ResizeMode
  tintColor: Color
}
```

#### shadows

Image shadows are derived exactly from the pixels.

<Preview withSource='none'>
  <Story name="styleBoxShadow">
    <Stories.styleBoxShadow />
  </Story>
</Preview>

#### tintColor

Tint color is applied to all opaque pixels.

<Preview withSource='none'>
  <Story name="styleTintColor">
    <Stories.styleTintColor />
  </Story>
</Preview>

## Static methods

### getSize(url, callback)

```js
type GetSize = (url: string, success: (width, height) => {}, failure: function) => void
```

Retrieve the width and height (in pixels) of an image prior to displaying it.
This method can fail if the image cannot be found, or fails to download.

(In order to retrieve the image dimensions, the image may first need to be
loaded or downloaded, after which it will be cached. This means that in
principle you could use this method to preload images, however, it is not
optimized for that purpose, and may in future be implemented in a way that does
not fully load/download the image data.)

```js
const uri = 'https://www.domain.com/img-1.jpg';
Image.getSize(uri, ((width, height) => {
  // image size is available
});
```

<Preview withSource='none'>
  <Story name="getSize">
    <Stories.getSize />
  </Story>
</Preview>

### prefetch(url)

```js
type Prefetch = (url: string) => Promise
```

Prefetches a remote image for later use by downloading it. Once an image has been
prefetched it is assumed to be in native browser caches and available for immediate
rendering.

```js
const uri = 'https://www.domain.com/img-1.jpg';
Image.prefetch(uri).then(() => {
  // image is now prefetched
});
```

<Preview withSource='none'>
  <Story name="prefetch">
    <Stories.prefetch />
  </Story>
</Preview>

### queryCache(list)

Performs cache interrogation. Returns a mapping from URL to cache status:
"disk", "memory", "disk/memory". If a requested URL is not in the mapping, it
means it's not in the cache.

```js
Image.queryCache([
  'https://www.domain.com/img-1.jpg',
  'https://www.domain.com/img-2.missing',
  'https://www.domain.com/img-3.jpg'
]).then(res => {
  expect(res).toEqual({
    'https://www.domain.com/img-1.jpg': 'disk/memory',
    'https://www.domain.com/img-3.jpg': 'disk/memory'
  });
});
```
