npm package: @macrominds/gallery
Description: Modern pure css image gallery using hidden inputs in desktop mode and scroll snapping in touch friendly mode.
Author: Thomas Praxl
Latest version: 0.5.0

= @macrominds/gallery

A modern image gallery that works without javascript.

It uses hidden `input type="radio"` and css translations to slide.

== Installation

[source,bash]
----
$ npm install @macrominds/gallery --save-dev
----

.In your scss
[source,scss]
----
@import "~@macrominds/gallery"
----

Alternatively, you can use the compiled version from
https://unpkg.com/@macrominds/gallery@latest/dist/index.css

.CSS
[source,html]
----
<link href="//unpkg.com/@macrominds/gallery@latest/dist/index.css" rel="stylesheet">
----

== Usage

Make sure to keep the following html structure.
You may want to use a server side script to generate the html.

.Using `img`
[source,html]
----
<div class="gallery">
    <input type="radio" name="s" id="s1" checked="">                                <1><2>
    <input type="radio" name="s" id="s2">                                           <3>
    <input type="radio" name="s" id="s3">                                           <4>
    <label for="s1"></label>                                                        <5>
    <label for="s2"></label>
    <label for="s3"></label>
    <img src="https://picsum.photos/seed/mac/800/600" alt="" class="first-item">    <6>
    <img loading="lazy" src="https://picsum.photos/seed/ro/800/600" alt="">         <7>
    <img loading="lazy" src="https://picsum.photos/seed/minds/800/600" alt=""></div>
----
<1> Provide one `<input type="radio">` per image
<2> Add checked attribute to first `<input type="radio">`
<3> Same name for the radio buttons – e.g. `name="s"` – (but most likely you want it to be different per gallery)
<4> Different `id` for each `<input type="radio">` – e.g. `id="s1"`, `id="s2"`, `id="s3"`
<5> One empty label per image (will be used to display the arrows)
<6> Assign `class="first-item"` to first image
<7> add `loading="lazy"` to let modern browsers postpone loading images until needed – see https://caniuse.com/#feat=loading-lazy-attr[Browsersupport]

.Using `figure`
[source,html]
----
<div class="gallery">
    <input type="radio" name="f" id="f1" checked="">
    <input type="radio" name="f" id="f2">
    <input type="radio" name="f" id="f3">
    <label for="f1"></label>
    <label for="f2"></label>
    <label for="f3"></label>
    <figure class="first-item"><img src="http://placehold.it/800x600" alt="alt"><figcaption>caption1</figcaption></figure>
    <figure><img src="http://placehold.it/800x600" alt="alt"><figcaption>caption2</figcaption></figure>
    <figure><img src="http://placehold.it/800x600" alt="alt"><figcaption>caption3</figcaption></figure>
</div>
----

=== Touch support

Add class `touch-enabled` to a parent element if you want touch support. Arrows will go away in that case:

[source,html]
----
<body class="touch-enabled">
…
<div class="gallery">
----

The touch enabled mode uses native scrolling and snaps to scroll positions using css.

Per default, the scrollbar stays visible in touch mode to avoid accessibility issues.
But you can hide the scrollbar if you wish:

[source,html]
----
<body class="touch-enabled">
…
<div class="gallery hide-scrollbar">
----


== Contribute

To build this package on your own, run

[source,bash]
----
$ npm run build
----

This will compile link:src/index.scss[] to link:dist/index.css[] and copy all files from link:src[] to link:dist[].

== TODO

- Build css and commit the artifact to git so that users don't need a scss processor
- Provide Android 4.4 compatible fallback (maybe)
- Provide touch friendly version
- Recheck and document browser compatibility