@vysmo/slideshow-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maesto LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @vysmo/slideshow-react
+
+React bindings for [`@vysmo/slideshow`](https://www.npmjs.com/package/@vysmo/slideshow). Drop-in image slideshow driven by any of the 60 [`@vysmo/transitions`](https://www.npmjs.com/package/@vysmo/transitions) shaders, with opt-in arrows / dots / counter / progress / captions — wrapped in one component plus a hook for imperative control.
+
+[Live demos](https://vysmo.com/slideshow) · [Source](https://github.com/vysmodev)
+
+## Install
+
+```bash
+pnpm add @vysmo/slideshow @vysmo/slideshow-react
+```
+
+`react` ≥ 18 is a peer dependency. `@vysmo/transitions` is required if you want to pass a specific transition (`dissolve` is the default).
+
+## Quick start
+
+```tsx
+import { Slideshow } from "@vysmo/slideshow-react";
+import { paintBleed } from "@vysmo/transitions";
+
+export function Hero() {
+  return (
+    <Slideshow
+      slides={["/01.jpg", "/02.jpg", "/03.jpg"]}
+      transition={paintBleed}
+      transitionDuration={900}
+      autoplayDelay={4000}
+      arrows
+      dots
+      style={{ width: "100%", aspectRatio: "16 / 9" }}
+    />
+  );
+}
+```
+
+The component renders a `<div>`, mounts the slideshow into it, and tears down on unmount. Click halves, keyboard nav, and autoplay are wired by default; arrows / dots / counter / progress / captions are opt-in.
+
+## Per-slide transition
+
+Pass a function `(from, to) => Transition` to vary the transition per slide change:
+
+```tsx
+import { paintBleed, glitch, ripple, crossZoom } from "@vysmo/transitions";
+
+const transitions = [paintBleed, glitch, ripple, crossZoom];
+
+<Slideshow
+  slides={[...]}
+  transition={(from, to) => transitions[to % transitions.length]!}
+/>
+```
+
+## Imperative control
+
+For custom Next/Prev buttons, scroll-bound `go()`, autoplay toggles, etc., use the hook and call methods on the returned handle:
+
+```tsx
+import { useRef } from "react";
+import { useSlideshow } from "@vysmo/slideshow-react";
+
+function ControlledSlideshow({ slides }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const slideshow = useSlideshow(ref, { slides, autoplayDelay: 4000 });
+
+  return (
+    <>
+      <div ref={ref} style={{ width: "100%", aspectRatio: "16 / 9" }} />
+      <button onClick={() => slideshow?.prev()}>‹</button>
+      <button onClick={() => slideshow?.next()}>›</button>
+      <button onClick={() => slideshow?.isPlaying ? slideshow.pause() : slideshow?.play()}>
+        Play / Pause
+      </button>
+    </>
+  );
+}
+```
+
+The handle is `null` until the slideshow is mounted; use optional chaining or a guard.
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `slides` | `readonly SlideSource[]` | — | URLs (decoded), `HTMLImageElement`s, or canvases. |
+| `initial` | `number` | `0` | Starting index. |
+| `transition` | `Transition \| (from, to) => Transition` | `dissolve` | Single transition or per-slide selector. |
+| `transitionDuration` | `number` | `800` | Transition ms. |
+| `ease` | `EasingFn` | linear | Easing for the transition. |
+| `autoplayDelay` | `number` | — | Dwell time in ms; omit / `0` to disable. |
+| `autoplay` | `boolean` | `true` if `autoplayDelay > 0` | Start autoplay on mount. |
+| `loop` | `boolean` | `true` | Wrap last → first. |
+| `clickNavigation` | `boolean` | `true` | Click halves to advance. |
+| `keyboardNavigation` | `boolean` | `true` | Arrow keys, Home/End, Space. |
+| `pauseOnHidden` | `boolean` | `true` | Pause autoplay while the tab is hidden. |
+| `pauseOnHover` | `boolean` | `false` | Pause autoplay on hover. |
+| `swipeNavigation` | `boolean \| SwipeOptions` | `false` | Touch / pointer swipe. |
+| `arrows` | `boolean \| ArrowsOptions` | `false` | Visible nav arrows. |
+| `dots` | `boolean \| DotsOptions` | `false` | Page-indicator dots. |
+| `counter` | `boolean \| CounterOptions` | `false` | Slide-counter overlay. |
+| `progress` | `boolean \| ProgressOptions` | `false` | Autoplay countdown bar. |
+| `captions` | `false \| CaptionsOptions` | `false` | Per-slide caption overlay. |
+| `ariaLabel` | `string` | `"Slideshow"` | Accessible label. |
+| `onChange` | `(current, previous) => void` | — | Slide change callback. |
+| `onTransitionStart` | `(from, to) => void` | — | Transition begins. |
+| `onTransitionEnd` | `(from, to) => void` | — | Transition ends. |
+| `className` | `string` | — | Forwarded to the host `<div>`. |
+| `style` | `CSSProperties` | — | Forwarded to the host `<div>`. Size the slideshow here. |
+
+## SSR
+
+The wrapper is SSR-safe: `useEffect` bodies don't run on the server, and the module body itself doesn't touch `window` / `document`. Server renders an empty `<div>`; client mounts the slideshow.
+
+## License
+
+MIT.

package/dist/Slideshow.d.ts

@@ -0,0 +1,62 @@
+import type { CSSProperties, ReactElement } from "react";
+import { type SlideshowOptions, type SlideSource, type ArrowsOptions, type DotsOptions, type CounterOptions, type ProgressOptions, type CaptionsOptions, type SwipeOptions } from "@vysmo/slideshow";
+export interface SlideshowProps {
+    /** Slide sources. URL strings (decoded), `HTMLImageElement`s, or canvases. */
+    slides: readonly SlideSource[];
+    /** Starting slide index. Default `0`. */
+    initial?: number;
+    /** Transition (or `(from, to) => Transition` selector for variety). Default `dissolve`. */
+    transition?: SlideshowOptions["transition"];
+    /** Transition duration ms. Default `800`. */
+    transitionDuration?: number;
+    /** Easing for transition progress. Default linear. */
+    ease?: SlideshowOptions["ease"];
+    /** Autoplay dwell time ms. `0` / omit to disable. */
+    autoplayDelay?: number;
+    /** Start autoplay on mount. Defaults to `true` when `autoplayDelay > 0`. */
+    autoplay?: boolean;
+    /** Wrap last → first. Default `true`. */
+    loop?: boolean;
+    /** Click halves to navigate. Default `true`. */
+    clickNavigation?: boolean;
+    /** Arrow keys / Home / End / Space. Default `true`. */
+    keyboardNavigation?: boolean;
+    /** Pause autoplay while the tab is hidden. Default `true`. */
+    pauseOnHidden?: boolean;
+    /** Pause autoplay while the pointer is over the slideshow. Default `false`. */
+    pauseOnHover?: boolean;
+    /** Touch / pointer swipe. */
+    swipeNavigation?: boolean | SwipeOptions;
+    /** Visible nav arrows. */
+    arrows?: boolean | ArrowsOptions;
+    /** Page-indicator dots. */
+    dots?: boolean | DotsOptions;
+    /** Slide-counter text overlay. */
+    counter?: boolean | CounterOptions;
+    /** Autoplay countdown bar. */
+    progress?: boolean | ProgressOptions;
+    /** Per-slide caption overlay. */
+    captions?: false | CaptionsOptions;
+    /** Accessible label. Default `"Slideshow"`. */
+    ariaLabel?: string;
+    /** Fires when the active slide changes. */
+    onChange?: (current: number, previous: number) => void;
+    /** Fires when a transition begins. */
+    onTransitionStart?: (from: number, to: number) => void;
+    /** Fires when a transition finishes. */
+    onTransitionEnd?: (from: number, to: number) => void;
+    /** Forwarded to the host `<div>`. */
+    className?: string;
+    /** Forwarded to the host `<div>`. Size the slideshow here (width / height). */
+    style?: CSSProperties;
+}
+/**
+ * React wrapper around `@vysmo/slideshow`. Renders a `<div>` host,
+ * mounts the slideshow into it, and tears down on unmount.
+ *
+ * For imperative control (custom Next/Prev buttons, scroll-driven
+ * `go()`), reach for `useSlideshow(containerRef, options)` instead — it
+ * returns the handle.
+ */
+export declare function Slideshow({ slides, initial, transition, transitionDuration, ease, autoplayDelay, autoplay, loop, clickNavigation, keyboardNavigation, pauseOnHidden, pauseOnHover, swipeNavigation, arrows, dots, counter, progress, captions, ariaLabel, onChange, onTransitionStart, onTransitionEnd, className, style, }: SlideshowProps): ReactElement;
+//# sourceMappingURL=Slideshow.d.ts.map

package/dist/Slideshow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Slideshow.d.ts","sourceRoot":"","sources":["../src/Slideshow.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AACzD,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IAC/B,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAC5C,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAChC,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yCAAyC;IACzC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gDAAgD;IAChD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,uDAAuD;IACvD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,8DAA8D;IAC9D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,6BAA6B;IAC7B,eAAe,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IACzC,0BAA0B;IAC1B,MAAM,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IACjC,2BAA2B;IAC3B,IAAI,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IAC7B,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IACnC,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IACrC,iCAAiC;IACjC,QAAQ,CAAC,EAAE,KAAK,GAAG,eAAe,CAAC;IACnC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACvD,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACvD,wCAAwC;IACxC,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACrD,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,EACxB,MAAM,EACN,OAAO,EACP,UAAU,EACV,kBAAkB,EAClB,IAAI,EACJ,aAAa,EACb,QAAQ,EACR,IAAI,EACJ,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,eAAe,EACf,MAAM,EACN,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,YAAY,CA6E/B"}

package/dist/Slideshow.js

@@ -0,0 +1,99 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { createSlideshow, } from "@vysmo/slideshow";
+/**
+ * React wrapper around `@vysmo/slideshow`. Renders a `<div>` host,
+ * mounts the slideshow into it, and tears down on unmount.
+ *
+ * For imperative control (custom Next/Prev buttons, scroll-driven
+ * `go()`), reach for `useSlideshow(containerRef, options)` instead — it
+ * returns the handle.
+ */
+export function Slideshow({ slides, initial, transition, transitionDuration, ease, autoplayDelay, autoplay, loop, clickNavigation, keyboardNavigation, pauseOnHidden, pauseOnHover, swipeNavigation, arrows, dots, counter, progress, captions, ariaLabel, onChange, onTransitionStart, onTransitionEnd, className, style, }) {
+    const containerRef = useRef(null);
+    const handleRef = useRef(null);
+    // Stash callbacks so reference changes don't recreate the slideshow.
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    const onTransitionStartRef = useRef(onTransitionStart);
+    onTransitionStartRef.current = onTransitionStart;
+    const onTransitionEndRef = useRef(onTransitionEnd);
+    onTransitionEndRef.current = onTransitionEnd;
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        const opts = { container, slides };
+        if (initial !== undefined)
+            opts.initial = initial;
+        if (transition !== undefined)
+            opts.transition = transition;
+        if (transitionDuration !== undefined)
+            opts.transitionDuration = transitionDuration;
+        if (ease !== undefined)
+            opts.ease = ease;
+        if (autoplayDelay !== undefined)
+            opts.autoplayDelay = autoplayDelay;
+        if (autoplay !== undefined)
+            opts.autoplay = autoplay;
+        if (loop !== undefined)
+            opts.loop = loop;
+        if (clickNavigation !== undefined)
+            opts.clickNavigation = clickNavigation;
+        if (keyboardNavigation !== undefined)
+            opts.keyboardNavigation = keyboardNavigation;
+        if (pauseOnHidden !== undefined)
+            opts.pauseOnHidden = pauseOnHidden;
+        if (pauseOnHover !== undefined)
+            opts.pauseOnHover = pauseOnHover;
+        if (swipeNavigation !== undefined)
+            opts.swipeNavigation = swipeNavigation;
+        if (arrows !== undefined)
+            opts.arrows = arrows;
+        if (dots !== undefined)
+            opts.dots = dots;
+        if (counter !== undefined)
+            opts.counter = counter;
+        if (progress !== undefined)
+            opts.progress = progress;
+        if (captions !== undefined)
+            opts.captions = captions;
+        if (ariaLabel !== undefined)
+            opts.ariaLabel = ariaLabel;
+        const handle = createSlideshow(opts);
+        handleRef.current = handle;
+        const offChange = handle.on("change", (cur, prev) => onChangeRef.current?.(cur, prev));
+        const offStart = handle.on("transitionstart", (from, to) => onTransitionStartRef.current?.(from, to));
+        const offEnd = handle.on("transitionend", (from, to) => onTransitionEndRef.current?.(from, to));
+        return () => {
+            offChange();
+            offStart();
+            offEnd();
+            handle.destroy();
+            handleRef.current = null;
+        };
+    }, [
+        slides,
+        initial,
+        transition,
+        transitionDuration,
+        ease,
+        autoplayDelay,
+        autoplay,
+        loop,
+        clickNavigation,
+        keyboardNavigation,
+        pauseOnHidden,
+        pauseOnHover,
+        swipeNavigation,
+        arrows,
+        dots,
+        counter,
+        progress,
+        captions,
+        ariaLabel,
+    ]);
+    return _jsx("div", { ref: containerRef, className: className, style: style });
+}
+//# sourceMappingURL=Slideshow.js.map

package/dist/Slideshow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Slideshow.js","sourceRoot":"","sources":["../src/Slideshow.tsx"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Slideshow, type SlideshowProps } from "./Slideshow.js";
+export { useSlideshow } from "./use-slideshow.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Slideshow } from "./Slideshow.js";
+export { useSlideshow } from "./use-slideshow.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAuB,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/use-slideshow.d.ts

@@ -0,0 +1,13 @@
+import type { RefObject } from "react";
+import { type SlideshowHandle, type SlideshowOptions } from "@vysmo/slideshow";
+/**
+ * Mount a slideshow into a container ref you own and get the handle for
+ * imperative control (`next` / `prev` / `go` / `play` / `pause`).
+ *
+ * Re-creates the slideshow when *any* member of the `options` object
+ * changes — memoize the options and the `slides` array if you want
+ * stability. Returns `null` until the container is in the DOM and the
+ * slideshow is mounted.
+ */
+export declare function useSlideshow(containerRef: RefObject<HTMLElement | null>, options: Omit<SlideshowOptions, "container">): SlideshowHandle | null;
+//# sourceMappingURL=use-slideshow.d.ts.map

package/dist/use-slideshow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-slideshow.d.ts","sourceRoot":"","sources":["../src/use-slideshow.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAC3C,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,CAAC,GAC3C,eAAe,GAAG,IAAI,CAkBxB"}

package/dist/use-slideshow.js

@@ -0,0 +1,31 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import { createSlideshow, } from "@vysmo/slideshow";
+/**
+ * Mount a slideshow into a container ref you own and get the handle for
+ * imperative control (`next` / `prev` / `go` / `play` / `pause`).
+ *
+ * Re-creates the slideshow when *any* member of the `options` object
+ * changes — memoize the options and the `slides` array if you want
+ * stability. Returns `null` until the container is in the DOM and the
+ * slideshow is mounted.
+ */
+export function useSlideshow(containerRef, options) {
+    const [handle, setHandle] = useState(null);
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        const h = createSlideshow({ ...optionsRef.current, container });
+        setHandle(h);
+        return () => {
+            h.destroy();
+            setHandle(null);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [containerRef, options]);
+    return handle;
+}
+//# sourceMappingURL=use-slideshow.js.map

package/dist/use-slideshow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-slideshow.js","sourceRoot":"","sources":["../src/use-slideshow.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEpD,OAAO,EACL,eAAe,GAGhB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,YAA2C,EAC3C,OAA4C;IAE5C,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAyB,IAAI,CAAC,CAAC;IACnE,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACnC,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;IAE7B,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC;QACvC,IAAI,CAAC,SAAS;YAAE,OAAO;QACvB,MAAM,CAAC,GAAG,eAAe,CAAC,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;QAChE,SAAS,CAAC,CAAC,CAAC,CAAC;QACb,OAAO,GAAG,EAAE;YACV,CAAC,CAAC,OAAO,EAAE,CAAC;YACZ,SAAS,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC,CAAC;QACF,uDAAuD;IACzD,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IAE5B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@vysmo/slideshow-react",
+  "version": "0.1.0",
+  "description": "React bindings for @vysmo/slideshow — a <Slideshow> component that drives any of the 60 WebGL transitions between slides, with opt-in arrows / dots / counter / progress / captions; useSlideshow hook for imperative control.",
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "slideshow",
+    "carousel",
+    "webgl",
+    "transitions",
+    "vysmo"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "@vysmo/slideshow": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/browser": "^3.2.4",
+    "playwright": "^1.59.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@vysmo/slideshow": "0.1.0",
+    "@vysmo/transitions": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run && vitest run --config vitest.ssr.config.ts",
+    "test:browser": "vitest run",
+    "test:ssr": "vitest run --config vitest.ssr.config.ts",
+    "test:watch": "vitest"
+  }
+}

package/src/Slideshow.tsx

@@ -0,0 +1,179 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import type { CSSProperties, ReactElement } from "react";
+import {
+  createSlideshow,
+  type SlideshowHandle,
+  type SlideshowOptions,
+  type SlideSource,
+  type ArrowsOptions,
+  type DotsOptions,
+  type CounterOptions,
+  type ProgressOptions,
+  type CaptionsOptions,
+  type SwipeOptions,
+} from "@vysmo/slideshow";
+
+export interface SlideshowProps {
+  /** Slide sources. URL strings (decoded), `HTMLImageElement`s, or canvases. */
+  slides: readonly SlideSource[];
+  /** Starting slide index. Default `0`. */
+  initial?: number;
+  /** Transition (or `(from, to) => Transition` selector for variety). Default `dissolve`. */
+  transition?: SlideshowOptions["transition"];
+  /** Transition duration ms. Default `800`. */
+  transitionDuration?: number;
+  /** Easing for transition progress. Default linear. */
+  ease?: SlideshowOptions["ease"];
+  /** Autoplay dwell time ms. `0` / omit to disable. */
+  autoplayDelay?: number;
+  /** Start autoplay on mount. Defaults to `true` when `autoplayDelay > 0`. */
+  autoplay?: boolean;
+  /** Wrap last → first. Default `true`. */
+  loop?: boolean;
+  /** Click halves to navigate. Default `true`. */
+  clickNavigation?: boolean;
+  /** Arrow keys / Home / End / Space. Default `true`. */
+  keyboardNavigation?: boolean;
+  /** Pause autoplay while the tab is hidden. Default `true`. */
+  pauseOnHidden?: boolean;
+  /** Pause autoplay while the pointer is over the slideshow. Default `false`. */
+  pauseOnHover?: boolean;
+  /** Touch / pointer swipe. */
+  swipeNavigation?: boolean | SwipeOptions;
+  /** Visible nav arrows. */
+  arrows?: boolean | ArrowsOptions;
+  /** Page-indicator dots. */
+  dots?: boolean | DotsOptions;
+  /** Slide-counter text overlay. */
+  counter?: boolean | CounterOptions;
+  /** Autoplay countdown bar. */
+  progress?: boolean | ProgressOptions;
+  /** Per-slide caption overlay. */
+  captions?: false | CaptionsOptions;
+  /** Accessible label. Default `"Slideshow"`. */
+  ariaLabel?: string;
+  /** Fires when the active slide changes. */
+  onChange?: (current: number, previous: number) => void;
+  /** Fires when a transition begins. */
+  onTransitionStart?: (from: number, to: number) => void;
+  /** Fires when a transition finishes. */
+  onTransitionEnd?: (from: number, to: number) => void;
+  /** Forwarded to the host `<div>`. */
+  className?: string;
+  /** Forwarded to the host `<div>`. Size the slideshow here (width / height). */
+  style?: CSSProperties;
+}
+
+/**
+ * React wrapper around `@vysmo/slideshow`. Renders a `<div>` host,
+ * mounts the slideshow into it, and tears down on unmount.
+ *
+ * For imperative control (custom Next/Prev buttons, scroll-driven
+ * `go()`), reach for `useSlideshow(containerRef, options)` instead — it
+ * returns the handle.
+ */
+export function Slideshow({
+  slides,
+  initial,
+  transition,
+  transitionDuration,
+  ease,
+  autoplayDelay,
+  autoplay,
+  loop,
+  clickNavigation,
+  keyboardNavigation,
+  pauseOnHidden,
+  pauseOnHover,
+  swipeNavigation,
+  arrows,
+  dots,
+  counter,
+  progress,
+  captions,
+  ariaLabel,
+  onChange,
+  onTransitionStart,
+  onTransitionEnd,
+  className,
+  style,
+}: SlideshowProps): ReactElement {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const handleRef = useRef<SlideshowHandle | null>(null);
+
+  // Stash callbacks so reference changes don't recreate the slideshow.
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  const onTransitionStartRef = useRef(onTransitionStart);
+  onTransitionStartRef.current = onTransitionStart;
+  const onTransitionEndRef = useRef(onTransitionEnd);
+  onTransitionEndRef.current = onTransitionEnd;
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const opts: SlideshowOptions = { container, slides };
+    if (initial !== undefined) opts.initial = initial;
+    if (transition !== undefined) opts.transition = transition;
+    if (transitionDuration !== undefined) opts.transitionDuration = transitionDuration;
+    if (ease !== undefined) opts.ease = ease;
+    if (autoplayDelay !== undefined) opts.autoplayDelay = autoplayDelay;
+    if (autoplay !== undefined) opts.autoplay = autoplay;
+    if (loop !== undefined) opts.loop = loop;
+    if (clickNavigation !== undefined) opts.clickNavigation = clickNavigation;
+    if (keyboardNavigation !== undefined) opts.keyboardNavigation = keyboardNavigation;
+    if (pauseOnHidden !== undefined) opts.pauseOnHidden = pauseOnHidden;
+    if (pauseOnHover !== undefined) opts.pauseOnHover = pauseOnHover;
+    if (swipeNavigation !== undefined) opts.swipeNavigation = swipeNavigation;
+    if (arrows !== undefined) opts.arrows = arrows;
+    if (dots !== undefined) opts.dots = dots;
+    if (counter !== undefined) opts.counter = counter;
+    if (progress !== undefined) opts.progress = progress;
+    if (captions !== undefined) opts.captions = captions;
+    if (ariaLabel !== undefined) opts.ariaLabel = ariaLabel;
+
+    const handle = createSlideshow(opts);
+    handleRef.current = handle;
+
+    const offChange = handle.on("change", (cur, prev) => onChangeRef.current?.(cur, prev));
+    const offStart = handle.on("transitionstart", (from, to) =>
+      onTransitionStartRef.current?.(from, to),
+    );
+    const offEnd = handle.on("transitionend", (from, to) =>
+      onTransitionEndRef.current?.(from, to),
+    );
+
+    return () => {
+      offChange();
+      offStart();
+      offEnd();
+      handle.destroy();
+      handleRef.current = null;
+    };
+  }, [
+    slides,
+    initial,
+    transition,
+    transitionDuration,
+    ease,
+    autoplayDelay,
+    autoplay,
+    loop,
+    clickNavigation,
+    keyboardNavigation,
+    pauseOnHidden,
+    pauseOnHover,
+    swipeNavigation,
+    arrows,
+    dots,
+    counter,
+    progress,
+    captions,
+    ariaLabel,
+  ]);
+
+  return <div ref={containerRef} className={className} style={style} />;
+}

package/src/__tests__/Slideshow.test.tsx

@@ -0,0 +1,111 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createRoot, type Root } from "react-dom/client";
+import { act } from "react";
+import { paintBleed } from "@vysmo/transitions";
+import { Slideshow } from "../Slideshow.js";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function makeSolid(r: number, g: number, b: number, size = 32): HTMLCanvasElement {
+  const canvas = document.createElement("canvas");
+  canvas.width = size;
+  canvas.height = size;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("2D context unavailable");
+  ctx.fillStyle = `rgb(${r}, ${g}, ${b})`;
+  ctx.fillRect(0, 0, size, size);
+  return canvas;
+}
+
+describe("<Slideshow>", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    container.style.width = "200px";
+    container.style.height = "200px";
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => {
+      root.unmount();
+    });
+    container.remove();
+  });
+
+  it("mounts a slideshow into its host div", async () => {
+    const slides = [makeSolid(255, 0, 0), makeSolid(0, 255, 0), makeSolid(0, 0, 255)];
+    await act(async () => {
+      root.render(<Slideshow slides={slides} />);
+    });
+    const canvas = container.querySelector("canvas");
+    expect(canvas).toBeTruthy();
+  });
+
+  it("forwards className and style to the host", async () => {
+    const slides = [makeSolid(255, 0, 0), makeSolid(0, 0, 255)];
+    await act(async () => {
+      root.render(
+        <Slideshow
+          slides={slides}
+          className="my-slideshow"
+          style={{ borderRadius: "8px" }}
+        />,
+      );
+    });
+    const host = container.firstElementChild as HTMLDivElement;
+    expect(host.classList.contains("my-slideshow")).toBe(true);
+    expect(host.style.borderRadius).toBe("8px");
+  });
+
+  it("renders chrome (arrows, dots) when opted in", async () => {
+    const slides = [makeSolid(255, 0, 0), makeSolid(0, 255, 0), makeSolid(0, 0, 255)];
+    await act(async () => {
+      root.render(<Slideshow slides={slides} arrows dots />);
+    });
+    // Both chrome elements live inside the slideshow's wrapper div.
+    const buttons = container.querySelectorAll("button");
+    expect(buttons.length).toBeGreaterThan(0);
+  });
+
+  it("wires onChange when a slide change happens", async () => {
+    const slides = [makeSolid(255, 0, 0), makeSolid(0, 255, 0), makeSolid(0, 0, 255)];
+    let captured: { current: number; previous: number } | null = null;
+    await act(async () => {
+      root.render(
+        <Slideshow
+          slides={slides}
+          transition={paintBleed}
+          transitionDuration={50}
+          onChange={(current, previous) => {
+            captured = { current, previous };
+          }}
+        />,
+      );
+    });
+    const wrapper = container.querySelector("[role='region']") as HTMLDivElement;
+    wrapper.focus();
+    wrapper.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true }),
+    );
+    await new Promise((r) => setTimeout(r, 200));
+    expect(captured).not.toBeNull();
+    expect(captured!.current).toBe(1);
+    expect(captured!.previous).toBe(0);
+  });
+
+  it("destroys on unmount without throwing", async () => {
+    const slides = [makeSolid(255, 0, 0), makeSolid(0, 255, 0)];
+    await act(async () => {
+      root.render(<Slideshow slides={slides} />);
+    });
+    await act(async () => {
+      root.unmount();
+    });
+    root = createRoot(container);
+    expect(container.querySelector("canvas")).toBeNull();
+  });
+});

package/src/__tests__/ssr.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+
+describe("SSR safety", () => {
+  it("window is undefined in this runtime", () => {
+    expect(typeof window).toBe("undefined");
+  });
+
+  it("module loads without DOM globals", async () => {
+    const mod = await import("../index.js");
+    expect(mod).toBeDefined();
+    expect(typeof mod.Slideshow).toBe("function");
+    expect(typeof mod.useSlideshow).toBe("function");
+  });
+});

package/src/index.ts

@@ -0,0 +1,2 @@
+export { Slideshow, type SlideshowProps } from "./Slideshow.js";
+export { useSlideshow } from "./use-slideshow.js";

package/src/use-slideshow.ts

@@ -0,0 +1,41 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import type { RefObject } from "react";
+import {
+  createSlideshow,
+  type SlideshowHandle,
+  type SlideshowOptions,
+} from "@vysmo/slideshow";
+
+/**
+ * Mount a slideshow into a container ref you own and get the handle for
+ * imperative control (`next` / `prev` / `go` / `play` / `pause`).
+ *
+ * Re-creates the slideshow when *any* member of the `options` object
+ * changes — memoize the options and the `slides` array if you want
+ * stability. Returns `null` until the container is in the DOM and the
+ * slideshow is mounted.
+ */
+export function useSlideshow(
+  containerRef: RefObject<HTMLElement | null>,
+  options: Omit<SlideshowOptions, "container">,
+): SlideshowHandle | null {
+  const [handle, setHandle] = useState<SlideshowHandle | null>(null);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const h = createSlideshow({ ...optionsRef.current, container });
+    setHandle(h);
+    return () => {
+      h.destroy();
+      setHandle(null);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [containerRef, options]);
+
+  return handle;
+}