# Venetian Blind - Skill Reference

> A full-bleed image slideshow whose transition splits the slide into N vertical strips that collapse (outgoing) or open (incoming) with a stagger, driven by one CSS `mask` of stacked gradients and one registered `@property` animated by `@keyframes`. A small TypeScript class (`mount()`) only sequences slides.

## What this teaches

- CSS `mask` with one `linear-gradient` layer per strip, each sized `calc(100% / N + 1px)` and positioned along x
- `@property` registration (`<number>`) so `@keyframes` can interpolate a custom property
- Deriving per-strip progress from one global progress var with `clamp()` and `calc()` (stagger without N keyframe blocks)
- A mask string built in JS and handed to CSS through a custom property (`--vm-vb-mask`)
- zIndex swap + `animationend` listener for stateless slide sequencing
- A `mount(container, options)` handle (`setParams`, `dispose`) and `[data-venetian-blind]` auto-init for the embed

## Core concept

One property, `--vm-vb-p`, runs 0 to 1 over `duration`. Every strip reads it, subtracts its own start offset (`i * stagger`), divides by the time window it has left and clamps to 0..1, so the strip count and stagger are plain numbers in the mask string, not extra keyframes. Strip progress is squared (ease-in), which makes the edges of each strip snap shut faster than a linear move. CSS owns all interpolation; JS only decides which slide carries `.active` and which sits on top.

## Use it

### Embed (no build step)

```html
<!-- the host element needs a size: the effect fills it (width/height 100%) -->
<script src="https://vanilla-motion.com/embed/venetian-blind/1.0.0/venetian-blind.js"></script>

<div data-venetian-blind
     data-direction="reveal"
     data-columns="8"
     data-stagger="6"
     data-duration="900"
     data-delay="3000"
     style="width: 100%; aspect-ratio: 16 / 9;">
  <!-- slides = every <img> inside the element, in order (any nesting). The effect replaces the
       children with its own slides and restores these on dispose(). -->
  <img src="/img/one.jpg" alt="">
  <img src="/img/two.jpg" alt="">
  <img src="/img/three.jpg" alt="">
</div>
```

- Every key of `defaults` is a kebab-case `data-*` attribute: `data-direction`, `data-columns`, `data-stagger`, `data-duration`, `data-delay`. Numbers go through `Number`; strings are used as-is. Omit an attribute to keep its default.
- There is no attribute for `images`: pass slides as child `<img>` elements (the effect reads `currentSrc || src`), or use `mount()` with `options.images`.
- With fewer than 2 slides nothing animates.
- The global is `window.VenetianBlind`: `VenetianBlind.init(root?)` starts the effect on every `[data-venetian-blind]` not yet running (call it after inserting markup late), `VenetianBlind.get(el)` returns the running handle, and `VenetianBlind.mount`, `.defaults`, `.VenetianBlind` are re-exported. It auto-runs on `DOMContentLoaded`.

```js
// elements added after load
document.body.insertAdjacentHTML("beforeend", '<div data-venetian-blind>...</div>');
VenetianBlind.init(document.body);
VenetianBlind.get(document.querySelector("[data-venetian-blind]")).setParams({ columns: 10 });
```

### Bundled apps

Get the files with `npx vanilla-motion add venetian-blind` (they land in `./vanilla-motion/venetian-blind/`).

```ts
import { mount } from "./vanilla-motion/venetian-blind/venetian-blind";

const container = document.querySelector<HTMLElement>("#hero")!; // give it a size
// handle type: { setParams(next: Partial<VenetianBlindParams>): void; dispose(): void }
const fx = mount(container, {
  images: ["/img/one.jpg", "/img/two.jpg", "/img/three.jpg"], // omit to use the <img> already inside
  direction: "reveal",
  columns: 8,
});

fx.setParams({ stagger: 4, delay: 3500 }); // merged over the current params, applied live
fx.dispose();                              // stops the timer, restores the container's original children
```

Also exported: `defaults`, the `VenetianBlind` class (`static readonly version`), and the types `VenetianBlindParams`, `VenetianBlindDirection`, `VenetianBlindOptions` (= `Partial<VenetianBlindParams> & { images?: string[] }`). No auto-init in the class.

### Params

| Key | Default | Range / options | Meaning |
| --- | --- | --- | --- |
| `direction` | `"collapse"` | `"collapse"`, `"reveal"` | `collapse`: the outgoing slide's strips shrink to their centre. `reveal`: the incoming slide's strips grow from their centre. |
| `columns` | `5` | 2 to 20, step 1 (the class clamps to at least 2) | Number of vertical strips. |
| `stagger` | `10` | 0 to 20, step 0.5 | Start offset between neighbouring strips, as a percentage of the transition. `0` moves all strips together. |
| `duration` | `800` | 100 to 4000 ms, step 50 | Length of one transition. |
| `delay` | `2000` | 500 to 10000 ms, step 100 | Time a slide stays before the next transition. Changing it restarts the timer. |

`setParams` applies `direction`, `columns`, `stagger` and `duration` immediately (the mask is rebuilt on every slide) and a running transition keeps going. Out-of-range values are not rejected by the class; the ranges are the control panel's.

## Key code

### HTML structure

```html
<!-- the class creates this inside your element; one slide = one absolutely stacked div -->
<div class="vm-venetian-blind" data-vm-vb-direction="collapse" style="--vm-vb-duration: 800ms">
  <div class="vm-venetian-blind__slide" style="--vm-vb-mask: ...; z-index: 2"><img src="..." alt=""></div>
  <div class="vm-venetian-blind__slide" style="--vm-vb-mask: ...; z-index: 0"><img src="..." alt=""></div>
</div>
```

Slide images get `alt=""` (decorative); the first one loads eagerly with high fetch priority. Put real alt text on the surrounding content if the images carry meaning.

### CSS - the effect

The class injects this once (`<style id="vm-venetian-blind-style">`, prefixed `vm-vb`).

```css
/* <number> so @keyframes can interpolate it; a <percentage> or untyped var would snap */
@property --vm-vb-p { syntax: "<number>"; inherits: false; initial-value: 0; }
@keyframes vm-venetian-blind { from { --vm-vb-p: 0; } to { --vm-vb-p: 1; } }

.vm-venetian-blind { position: relative; overflow: hidden; width: 100%; height: 100%; }
.vm-venetian-blind > .vm-venetian-blind__slide { position: absolute; inset: 0; }

/* collapse: every slide is masked. p = 0 leaves it fully visible, so idle slides need no special case */
.vm-venetian-blind[data-vm-vb-direction="collapse"] > .vm-venetian-blind__slide { mask: var(--vm-vb-mask); }
/* reveal: only the animating (incoming) slide is masked */
.vm-venetian-blind[data-vm-vb-direction="reveal"] > .vm-venetian-blind__slide.active { mask: var(--vm-vb-mask); }

/* linear: the easing lives in the mask (t * t), not in the animation */
.vm-venetian-blind > .vm-venetian-blind__slide.active {
  animation: vm-venetian-blind var(--vm-vb-duration) linear forwards;
}
```

The mask the class writes into `--vm-vb-mask` has one layer per strip `i` of `n`:

```css
/* t = clamp(0, (p - i*stagger) / window, 1)   window = 1 - (n-1)*stagger   q = t*t */
/* collapse: visible between q*50% and 100% - q*50%.  reveal: between 50% - q*50% and 50% + q*50% */
linear-gradient(to bottom, transparent 0 TOP, #000 TOP BOTTOM, transparent BOTTOM)
  X% 0 / calc(100% / n + 1px) 100% no-repeat   /* X = i/(n-1)*100; +1px overlap hides seams at fractional DPR */
```

With a large `columns * stagger`, the window shrinks (floored at 0.01), so keep `(columns - 1) * stagger` well under 100.

### JS - state machine

```ts
// the animated slide goes on top (z 2), the one it covers/uncovers below (z 1), the rest 0
const reveal = params.direction === "reveal";
const animated = slides[reveal ? incoming : outgoing]; // collapse animates the outgoing slide, reveal the incoming

if (reveal) setZ(incoming, outgoing); else setZ(outgoing, incoming);
animated.classList.add("active"); // starts the CSS animation

const done = () => {
  animated.removeEventListener("animationend", done);
  animated.classList.remove("active");
  slides[outgoing].style.zIndex = "0"; // park the old slide at the bottom
  slides[incoming].style.zIndex = "2"; // the new current slide sits on top
  current = incoming;
};
animated.addEventListener("animationend", done);
// ticks come from setInterval(advance, delay); advance() returns early while a transition is running
```

## Variants

### Collapse (default)

The outgoing slide is the animated one. Each strip's visible band shrinks to its centre (`top = q*50%`, `bottom = 100% - q*50%`), uncovering the next slide underneath. Every slide carries the mask; idle ones are at `p = 0`, i.e. fully visible. Preset: `{ direction: "collapse" }` with 4 `picsum.photos` images.

### Reveal (reveal)

The incoming slide is the animated one and sits on top. Its strips grow from each strip's centre (`top = 50% - q*50%`, `bottom = 50% + q*50%`) until the new image fills the frame. Only the `.active` slide is masked; the outgoing slide stays unmasked beneath. Preset: `{ direction: "reveal" }` with the same 4 images. Public clean view: `/venetian-blind/embed/reveal/`.

## Adapt to your layout

- **Strip count**: change `columns`. The mask is generated, so no CSS edits are needed.
- **Stagger vs duration**: strip `i` starts at `i * stagger`% and travels for `100 - (columns - 1) * stagger`% of `duration`. More columns or more stagger means shorter individual travel.
- **Timing**: `duration` is the transition, `delay` is the pause between transitions (so a full cycle is about `delay` ms apart, ticks start on a fixed interval).
- **Direction of strips**: strips are vertical bands that open vertically. For horizontal strips, swap `to bottom` for `to right`, the gradient size and position axes, in `buildMask()` (edit your copy of the class).
- **Easing**: change `q = t * t` in `buildMask()` for another curve; keep the animation `linear`.
- **Sizing**: the effect fills its container; give the container a width and height (or `aspect-ratio`). Images use `object-fit: cover`.
- **Class names**: `.vm-venetian-blind`, `__slide` and `.active` are prefixed to avoid collisions; style the container, not the internals.

## Browser support

`@property` (Chromium 85+, Firefox 128+, Safari 16.4+) · CSS `mask` with multiple gradient layers (all modern browsers) · `clamp()` inside `calc()` in gradient stops (modern evergreen). No polyfill path: where `@property` is unsupported the progress var does not interpolate, so feature-detect with `CSS.supports('@property', '--x')` and fall back to a static first image.

## Accessibility

The class does not check `prefers-reduced-motion`; do it before mounting.

```ts
if (!window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
  mount(container, { images }); // otherwise keep the first image as a plain <img>
}
```

The embed auto-starts on every `[data-venetian-blind]` and does not check it either: when motion is reduced, leave that attribute off the element and call `VenetianBlind.mount(el, options)` only when motion is allowed. Don't just shorten `duration`: skip the animation. Slides have empty `alt`, so keep meaningful text outside the slideshow.