## How it works
This package was designed to work within the existing FT architecture. This means integrating with and accepting input from Next ES-Interface. ES-Interface holds and processes article DOM content in a Cheerio instance.

This package therefore accepts a Cheerio instance as its main input. If provided a false input it would return undefined, and if provided content which is not a cheerio instance, it would return it and carry out no further processing.

Image-sets in this package rely on the image-set transforms in ES-Interface being applied. Therefore, all relevant transforms in ES-Interface should be applied to the Cheerio instance before it reaches this package. This means that Scrollytelling components need to be called after the image-set transform in ES-Interface.

To see a working example of the expected schema, view the .xml files contained in [/stories](https://github.com/Financial-Times/n-scrollytelling/blob/main/components/image/stories). To see the corresponding HTML output, build the Storybook demos locally (see [Demos](https://github.com/Financial-Times/n-scrollytelling/blob/main/components/image/README.md#demos) for details on how to do this) and view the corresponding .html files.

On receiving the cheerio instance, this package looks through the DOM represented in the instance for scrollable block XML - for sections that are supposed to be scrollable images. Scrollable blocks may possess different sections with different types of scrollable media - i.e some scrollable sections may not be scrollable images. This particular package is intended to only take care of scrollable images.

This package currently identifies which sections are scrollable image sections by finding any `<scrollable-section>` tags that either contain a `<figure>` tag (with a `<picture>` tag inside that). To be considered a valid scrollable image section, the section must contain no other tags - only those representing images (figures + picture) and text (`<scrollable-text>`).

On finding the scrollable images sections, the package removes any `<scrollable-text>` XML tags. The `<scrollable-text>` tag is only used for data organisation elsewhere and identifying text content here, but becomes superfluous for presentation purposes. The package then replaces the `<scrollable-section>` tags with the wrapping HTML (`<div class="n-scrollytelling-image-container"></div>`).

Finally, the scrollable-block tag is replaced with the topmost wrapping div (with class n-scrollytelling-fullscreen) which is just to make things fullscreen and to fill the viewport. This is done last and seperately because apart from indicating the boundaries where the processing is happening, it may eventually be moved to take place elsewhere (perhaps in its own package).


In summary, n-scrollytelling-image takes the input and:
1. Checks it has been passed a cheerio instance
2. Loads the appropriate set of processing functionality - cheerio actions in this case
3. Identifies scrollable images blocks by checking for sections containing images only and maybe text
4. Converts and replaces XML tags with HTML as required
5. Returns the updated cheerio instance