npm package: @siteone/react-components-image
Description: React image component
Author: Viktor Bezdek
Latest version: 0.0.8
Deprecated: Deprecated

# @siteone/react-image

React komponenta pro [obrázkovou mikroslužbu](https://git.siteone.cz/frontend/img). Zjednodušeně řečeno, můžete react-image použít jako náhradu klasického <img />, jen už nemusíte řešit optimalizaci obrázků.

## Obsah

- [Požadavky](#pozadavky)
- [Funkce](#funkce)
- [API](#api)
- [Používání](#pouzivani)
- [Konvence](#konvence)
- [Externí součásti](#externi-soucasti)
- [Správa a rozvoj projektu](#sprava-a-rozvoj-projektu)
- [Přispívání](#prispivani)
- [Licence](#licence)

## Požadavky
- React 16.x.x

## Funkce
- Formát - **automatická detekce podpory webp v prohlížeči**
  - řeší se pouze jednou na úrovni provideru, mikroslužba vždy vrátí webp formát pokud jej prohlížeč podporuje, jinak vrátí původní formát
- Změna velikosti
  - můžeme si říct pomocí parametrů *width* a *height* jakou přesně velikost obrázku chceme vrátit
  - a za pomoci parametru *scaleMode* můžeme nastavit jakym způsobem chceme, aby se obrázek oříznul
- Progresivní obrázek (Progressive)
  - [wiki](https://en.wikipedia.org/wiki/Progressive_Graphics_File)
  - v podstatě u většiny prohlížečů už je toto pro nás nepoužitelné, protože webp tuto funkci nepodporuje (je dost rychly i bez toho)

- Rotace (Rotate)
  - násobky 90°

- Převrácení stran (Flip)
  - převrátí buď x nebo y osu

- Rozmazání (Blur)
  - 0 - 100%

- Kvalita (Quality)
  - 0 - 100%

- TODO
  - Vygenerování retina obrázků
  - Výřez
  - Overlay image (watermark)
  

## Používání
  ### ImageProvider
  Nejprve musíme nadefinovat, kterou microslužbu budeme chtít používat. Budeme mít jednu obecnou **img.siteone.cz**, která bude určená pro testing a malé projekty (např. web S1). Velké projekty budou mít vlastní mikroslužbu na své doméně.


  Někde na nejvyšší úrovni aplikace:
  ```js
  import { ImageProvider } from '@siteone/react-image'

  const App = () => (
    <ImageProvider microserviceUrl="https://img.siteone.cz" baseImgComponent="img" baseImgBoxComponent="div">
      // ... layout, children, w/e
    </ImageProvider>
  )
  ```

## API
  ### ImageProvider
  Jak název napovídá, ImageProvider je komponenta, která nastavuje context pro všechny obrázky v aplikaci. Nedělá ale jen to, ale i zjišťuje zdali náš prohlížeč podporuje úžasný webp formát a říká komponentám jaký formát obrázku pro výstup má použít.

  #### Jaké props komponenta přijámá
  **microserviceUrl** : string [required]

  url mikroslužby
  - každý velký projekt bude mít vlastní službu, abychom rozmělnili náročnost na server a potenciální útoky a abychom měli jistotu, že nám pád jedné služby nerozbije všechny projekty
  
  ```js
  <ImageProvider microserviceUrl="https://img.siteone.cz" />
  ```
  -----
  **baseImgComponent** : React.Node | string [optional] (default: `"img"`)

  Možnost nastavit celé aplikaci komponentu, která se bude renderovat při použití `<Image />`

  - defaultně používáme klasický img tag pro zpětnou kompatibilitu se staršími projekty
  - na nových projektech budeme chtít použít proxy komponentu `<Element is="img" />`, abychom mohli `Image` komponentu skinovat stejně jako ostatní komponenty DS
  - na AirBank například použijeme proxy komponentu `<Box tag="img" />` z *frack-components*

  ```js
  // AB
  const ImgComponent = () => <Box tag="img" />

  // DS
  const ImgComponent = () => <Element is="img" />

  <ImageProvider baseImgComponent={ImgComponent} />
  ```
  -----
  **baseImgBoxComponent** : React.Node | string [optional] (default: `"div"`)

  Stejně jako *baseImgComponent*, máme možnost nadefinovat komponentu, která se bude renderovat při použití `<ImageBox />` komponenty

  ```js
  // AB
  import { Box } from 'frack-components'

  // DS
  const Box = () => <Element is="div" />

  <ImageProvider baseImgBoxComponent={Box} />
  ```

### Image a ImageBox
Kompmonenty, které budeme nejvíce používat. Jsou context consumers a obě přijímají až na pár vyjímek stejné props, které definuji níže.

`<Image />` komponenta je přímá náhrada html tagu `<img />`. Mimo běžných attributů, který běžný `<img />` očekává, přijímá komponenta další, které předá mikroslužbě pro práci s obrázkem.

`<ImageBox />` použijeme, když chceme použít optimalizovaný obrázek jako css pozadí jakékoliv komponenty. Defaultní render komponentu nastavíme v provideru, ale přes attribut *tag* ji můžeme lokálně přetížit. Render komponenta musí splňovat jedinou podmínku, musí umět přijmout style attribut, kde dostane *background-image*.

#### Jaké props komponenty přijímají
**tag** : React.Node | string [optional] (default: nastavení v provideru)

Možnost lokálně přepsat render komponentu.

**src** : string [required]

Cesta k obrázku

**width** : number [optional]

**height** : number [optional]

**rotate** : 0 | 90 | 180 | 270 [optional]

**quality** : number [optional]

v procentech, tedy 0-100

**blur** : number [optional]

v procentech, tedy 0-100

**progressive** : boolean [optional]

pro nás už není tolik podstatné, protože webp tuto funkcionalitu nemá, ale pokud u jpegu chceme upřednostnit rychlost načtení před kvalitou.

**scaleMode** : 
    | 'fit'
    | 'downfit'
    | 'upfit'
    | 'fill'
    | 'fillAuto'
    | 'fillCenter'
    | 'fillNorth'
    | 'fillNortheast'
    | 'fillNorthwest'
    | 'fillEast'
    | 'fillWest'
    | 'fillSouth'
    | 'fillSoutheast'
    | 'fillSouthwest' [optional] (default: 'fillAuto')

**flip** : 'x' | 'y' [optional]



## Konvence

## Externí součásti
- https://git.siteone.cz/frontend/img
## Správa a rozvoj projektu

[Tomáš Sláma](mailto:tomas.slama@siteone.cz)

## Přispívání

PRs accepted.

## Licence

MIT © 2018 SiteOne, s.r.o


> React companion component for [image processing microservice](https://git.siteone.cz/frontend/img).


Takes image of any format and when browser supports it returns u webp format of that image. U can tell to miroservice how to take care of your image. Croping, scaling, blur, quality, rotating, flip sides

[Storybook](http://frack.git.siteone.cz/frack)

[Api doc](https://git.siteone.cz/frontend/img#usage)



## Usage example

```javascript
<ImageProvider microserviceUrl="https://img.frontend.company"> // somewhere at top level of app
  <Image
    rotate={50}
    progressive
    flip="x" // x || y
    quality={100} // quality of image in %
    src="https://upload.wikimedia.org/wikipedia/commons/d/d3/Michelangelo_Buonarroti_017.jpg" // img path
    blur={100} // quality of image in %
    scaleMode={scaleMode} // 'fit', 'downfit', 'upfit', 'fill', 'fill_auto', 'fill_center', 'fill_north', 'fill_northeast', 'fill_northwest', 'fill_east', 'fill_west', 'fill_south', 'fill_southeast', 'fill_southwest'
    width={500}
    height={500}
    alt="image description"
  />

    // ImageBox takes all params as Image expect alt, but instead of returning <img /> it will return as inlined backgroundImage
  <ImageBox tag="div" />
</ImageProvider>
```


<!-- 
## Development setup

Describe how to install all development dependencies and how to run an automated test-suite of some kind. Potentially do this for multiple platforms.

```sh
make install
npm test
```


-->