uix-image-magnify 0.2.2 → 0.2.4

package/README.md

@@ -2,7 +2,40 @@
 
 **Fast, accessible, SSR-safe image magnifier and product gallery for React & Next.js.**
 
-A lightweight, fully-typed React component set for zooming images with a lens, a side-by-side pane, inner pan-and-zoom, or a follow-style magnifier. Ships with a product-style gallery (thumbnails + arrows + counter), a headless slider hook, and SSR-safe variants that prevent hydration mismatches in Next.js App Router, Remix, etc.
+A lightweight, fully-typed React component set for zooming images with a lens, a side-by-side pane, inner pan-and-zoom, or a follow-style magnifier. Ships with a product-style gallery (thumbnails + arrows + counter), headless hooks, and SSR-safe variants that prevent hydration mismatches in Next.js App Router, Remix, and any other SSR framework.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Single Image Magnifier](#single-image-magnifier)
+  - [Zoom modes](#zoom-modes)
+  - [Zoom triggers](#zoom-triggers)
+  - [Inner mode panning](#inner-mode-panning)
+  - [Wheel zoom](#wheel-zoom)
+  - [Responsive behaviour](#responsive-behaviour)
+- [Product Gallery](#product-gallery)
+  - [Thumbnails](#thumbnails)
+  - [Controlled gallery](#controlled-gallery)
+  - [Custom arrows](#custom-arrows)
+  - [Disable features](#disable-features)
+  - [Side-by-side pane inside the gallery](#side-by-side-pane-inside-the-gallery)
+- [SSR & Next.js](#ssr--nextjs)
+- [Hooks](#hooks)
+  - [useImageSlider](#useimageslider)
+  - [useImageMagnify](#useimagemagnify)
+- [Props Reference](#props-reference)
+  - [ImageMagnifyProps](#imagemagnifyprops)
+  - [ImageMagnifyGalleryProps](#imagemagnifygalleryprops)
+- [Styling](#styling)
+- [Accessibility](#accessibility)
+- [TypeScript](#typescript)
+- [Package Exports](#package-exports)
+- [Browser Support](#browser-support)
+- [License](#license)
 
 ---
 
@@ -11,13 +44,14 @@ A lightweight, fully-typed React component set for zooming images with a lens, a
 - 🔍 **4 zoom modes** — `lens`, `side-by-side`, `inner`, `follow`
 - 🖱️ **6 zoom triggers** — `hover`, `click`, `double-click`, `hold`, `wheel`, `none`
 - 🖼️ **Product gallery** with thumbnails, arrows, counter, and loop
-- ♿ **Accessible** — keyboard nav, ARIA roles, screen-reader live region
+- ♿ **Accessible** — keyboard navigation, ARIA roles, live region, `aria-current` thumbnails
 - 🧠 **SSR-safe** — dedicated `/ssr` entry point eliminates hydration mismatches
 - 📱 **Responsive** — zoom pane automatically moves below the image on mobile
 - 🎨 **Customizable** — every part is styleable; arrows accept custom React nodes
 - 🪝 **Headless hooks** — `useImageMagnify`, `useImageSlider`
 - 🧩 **TypeScript-first** with strict prop types
 - 🌲 **Tree-shakeable** — `sideEffects: false`, ESM + CJS builds
+- ⚡ **Performance** — `requestAnimationFrame`-batched DOM writes; zero re-renders during zoom
 
 ---
 
@@ -33,6 +67,8 @@ pnpm add uix-image-magnify
 
 `react` and `react-dom` (`>=17`) are peer dependencies. `swiper` is installed automatically as a dependency for the gallery.
 
+**Requirements:** Node 18+ for the build toolchain (not for runtime). Modern evergreen browsers (see [Browser Support](#browser-support)).
+
 ---
 
 ## Quick Start
@@ -76,7 +112,7 @@ import { ImageMagnify } from "uix-image-magnify";
   lensShape="circle"
   lensSize={160}
   lazy
-/>
+/>;
 ```
 
 ### Zoom modes
@@ -88,27 +124,27 @@ import { ImageMagnify } from "uix-image-magnify";
 | `inner`        | The image itself scales and pans inside its own container.    |
 | `follow`       | A lens follows the cursor with an optional offset.            |
 
-> **Mobile:** on `side-by-side` + `panePosition="bottom"`, the pane flows below the image instead of being absolutely positioned — no overlap, no clipping.
-
 ### Zoom triggers
 
-| Trigger        | Behavior                                               |
-| -------------- | ------------------------------------------------------ |
-| `hover`        | Zooms while the pointer is over the image.             |
-| `click`        | Toggles zoom on click.                                 |
-| `double-click` | Toggles zoom on double-click.                          |
-| `hold`         | Zooms only while the pointer is pressed down.          |
-| `wheel`        | Scroll to zoom; supports `minZoomScale`/`maxZoomScale`.|
-| `none`         | Disables interaction (renders a plain image).          |
+| Trigger        | Behavior                                                  |
+| -------------- | --------------------------------------------------------- |
+| `hover`        | Zooms while the pointer is over the image.                |
+| `click`        | Toggles zoom on click.                                    |
+| `double-click` | Toggles zoom on double-click.                             |
+| `hold`         | Zooms only while the pointer is pressed down.             |
+| `wheel`        | Scroll to zoom; supports `minZoomScale` / `maxZoomScale`. |
+| `none`         | Disables interaction (renders a plain image).             |
 
-> On touch devices, interaction behaves as tap-to-toggle regardless of `zoomType` (except `none`).
+> **Touch devices:** interaction behaves as tap-to-toggle regardless of `zoomType` (except `none`).
+>
+> **Wheel mode:** on desktop, zoom is driven by the wheel event only — a plain click does not toggle zoom.
 
-### `inner` mode panning
+### Inner mode panning
 
 When `mode="inner"`, set `dragMode`:
 
 - `dragMode="follow"` (default) — the pixel under the cursor stays under the cursor.
-- `dragMode="pan"` — drag to pan around the zoomed image.
+- `dragMode="pan"` — drag to pan around the zoomed image. The image is **centered** the first time you zoom in.
 
 ```tsx
 <ImageMagnify
@@ -135,11 +171,17 @@ When `mode="inner"`, set `dragMode`:
 />
 ```
 
+### Responsive behaviour
+
+- On screens `≤ 768px` wide, `width` is forced to `"100%"`.
+- When `mode="side-by-side"` and the pane would render to the left/right on mobile, it automatically flows **below** the image instead — no overflow, no clipping.
+- The `useMediaQuery` hook is SSR-safe: it returns `false` during SSR and the first client render, then updates before paint.
+
 ---
 
 ## Product Gallery
 
-`ImageMagnifyGallery` combines a Swiper-powered slider with the magnifier. It supports thumbnails, arrows, a counter, loop, keyboard navigation, and adjacent-image preloading.
+`ImageMagnifyGallery` combines a Swiper-powered main slider with the magnifier and a lightweight thumbnail strip. It supports thumbnails, arrows, a counter, loop, keyboard navigation, and adjacent-image preloading.
 
 ```tsx
 import { ImageMagnifyGallery } from "uix-image-magnify";
@@ -162,6 +204,27 @@ const images = [
   thumbnailSize={72}
   thumbnailGap={10}
   onIndexChange={(i) => console.log("active:", i)}
+/>;
+```
+
+### Thumbnails
+
+Thumbnails are rendered as a **plain scrollable flex strip** of `<button>` elements — not a nested Swiper. This is significantly faster (no second carousel instance, no duplicated magnifier instances) and gives you full control over styling.
+
+- `thumbnailSize` — thumbnail width/height in px (default `80`).
+- `thumbnailGap` — gap between thumbnails in px (default `8`).
+- Clicking a thumbnail navigates the main slider.
+- The active thumbnail receives `aria-current="true"` and merges `thumbnailActiveStyle` over `thumbnailStyle`.
+
+```tsx
+<ImageMagnifyGallery
+  images={images}
+  alt="Product"
+  thumbnailSize={64}
+  thumbnailGap={12}
+  thumbnailContainerStyle={{ justifyContent: "center" }}
+  thumbnailStyle={{ borderRadius: 8 }}
+  thumbnailActiveStyle={{ borderColor: "#0af" }}
 />
 ```
 
@@ -175,9 +238,11 @@ const [active, setActive] = useState(0);
   alt="Product"
   activeIndex={active}
   onIndexChange={setActive}
-/>
+/>;
 ```
 
+When `activeIndex` is provided, the gallery becomes **controlled**: `onIndexChange` fires on every slide change, and external updates to `activeIndex` call `swiper.slideTo(...)`.
+
 ### Custom arrows
 
 ```tsx
@@ -191,6 +256,8 @@ const [active, setActive] = useState(0);
 />
 ```
 
+Arrow buttons are automatically disabled (`disabled` + `aria-disabled`) at the ends when `loop={false}`.
+
 ### Disable features
 
 ```tsx
@@ -206,22 +273,61 @@ const [active, setActive] = useState(0);
 />
 ```
 
+### Side-by-side pane inside the gallery
+
+Swiper applies `overflow: hidden` to its wrapper, so a `side-by-side` pane positioned `left` or `right` of the image will be **clipped** by the slide boundary. Options:
+
+1. Use `mode="lens"`, `mode="inner"`, or `mode="follow"` — these render inside the image bounds.
+2. Use `mode="side-by-side"` with `panePosition="bottom"` and give the slide enough vertical space.
+3. Pass `swiperStyle={{ overflow: "visible" }}` to let the pane escape the slide — note that adjacent slides will then be visible too.
+
+```tsx
+// Option 1: use lens mode
+<ImageMagnifyGallery images={images} alt="Product" mode="lens" />
+
+// Option 2: bottom pane
+<ImageMagnifyGallery
+  images={images}
+  alt="Product"
+  mode="side-by-side"
+  panePosition="bottom"
+  paneHeight={320}
+/>
+
+// Option 3: opt out of clipping
+<ImageMagnifyGallery
+  images={images}
+  alt="Product"
+  mode="side-by-side"
+  panePosition="right"
+  swiperStyle={{ overflow: "visible" }}
+/>
+```
+
 ---
 
 ## SSR & Next.js
 
-The magnifier touches `window`, `matchMedia`, and pointer events. To avoid hydration mismatches, this package ships **SSR-safe wrappers** under the `uix-image-magnify/ssr` entry point:
+The magnifier touches `window`, `matchMedia`, `ResizeObserver`, and pointer events. To avoid hydration mismatches, this package ships **SSR-safe wrappers** under the `uix-image-magnify/ssr` entry point:
 
 - `ImageMagnifySSR` — plain `<img>` on server + first client render, swaps to `<ImageMagnify>` after hydration.
 - `ImageMagnifyGallerySSR` — same approach for the gallery.
 
+Both non-SSR components are also re-exported from this entry point for convenience.
+
 ### Option 1 — Use the SSR wrappers (recommended)
 
 ```tsx
 // app/products/[id]/page.tsx  (Server Component-safe import)
 import { ImageMagnifySSR } from "uix-image-magnify/ssr";
 
-export default function ProductImage({ src, alt }: { src: string; alt: string }) {
+export default function ProductImage({
+  src,
+  alt,
+}: {
+  src: string;
+  alt: string;
+}) {
   return (
     <ImageMagnifySSR
       src={src}
@@ -247,11 +353,11 @@ import dynamic from "next/dynamic";
 
 const ImageMagnify = dynamic(
   () => import("uix-image-magnify").then((m) => m.ImageMagnify),
-  { ssr: false }
+  { ssr: false },
 );
 ```
 
-Both approaches produce zero hydration warnings. Option 1 keeps the SSR-rendered `<img>` visible before hydration so users see the image immediately.
+Both approaches produce zero hydration warnings. Option 1 keeps the SSR-rendered `<img>` visible before hydration so users see the image immediately (no layout shift, no blank frame).
 
 ### Remix / React Router
 
@@ -278,15 +384,26 @@ const { index, setIndex, prev, next, canPrev, canNext } = useImageSlider({
 
 **Options**
 
-| Option          | Type                      | Default | Description                    |
-| --------------- | ------------------------- | ------- | ------------------------------ |
-| `length`        | `number`                  | —       | Total items.                   |
-| `defaultIndex`  | `number`                  | `0`     | Initial index (uncontrolled).  |
-| `index`         | `number`                  | —       | Controlled index.              |
-| `onIndexChange` | `(index: number) => void` | —       | Fired when the index changes.  |
-| `loop`          | `boolean`                 | `true`  | Wrap around at the ends.       |
+| Option          | Type                      | Default | Description                   |
+| --------------- | ------------------------- | ------- | ----------------------------- |
+| `length`        | `number`                  | —       | Total items.                  |
+| `defaultIndex`  | `number`                  | `0`     | Initial index (uncontrolled). |
+| `index`         | `number`                  | —       | Controlled index.             |
+| `onIndexChange` | `(index: number) => void` | —       | Fired when the index changes. |
+| `loop`          | `boolean`                 | `true`  | Wrap around at the ends.      |
+
+**Returns**
 
-**Returns:** `{ index, setIndex, prev, next, canPrev, canNext }`.
+| Field      | Type                     | Description                                                 |
+| ---------- | ------------------------ | ----------------------------------------------------------- |
+| `index`    | `number`                 | Current (clamped) index.                                    |
+| `canPrev`  | `boolean`                | Whether a previous item exists (always `true` when `loop`). |
+| `canNext`  | `boolean`                | Whether a next item exists (always `true` when `loop`).     |
+| `setIndex` | `(next: number) => void` | Go to a specific index (wraps when `loop`).                 |
+| `prev`     | `() => void`             | Go to previous item.                                        |
+| `next`     | `() => void`             | Go to next item.                                            |
+
+`defaultIndex` is clamped to `[0, length - 1]`.
 
 ### `useImageMagnify`
 
@@ -312,8 +429,47 @@ const {
   zoomType: "hover",
   zoomScale: 2.5,
 });
+
+return (
+  <div ref={containerRef} {...handlers} style={{ position: "relative" }}>
+    <img
+      ref={imageRef}
+      src="/thumb.jpg"
+      alt=""
+      style={{ display: "block", width: "100%" }}
+    />
+    {isZoomed && (
+      <div
+        ref={paneRef}
+        style={{
+          position: "absolute",
+          left: "100%",
+          top: 0,
+          width: 400,
+          height: 400,
+          backgroundImage: bgImage ? `url("${bgImage}")` : undefined,
+          backgroundRepeat: "no-repeat",
+        }}
+      />
+    )}
+  </div>
+);
 ```
 
+**Return value**
+
+| Field          | Type                          | Description                                     |
+| -------------- | ----------------------------- | ----------------------------------------------- |
+| `isZoomed`     | `boolean`                     | Whether zoom is currently active.               |
+| `zoomScale`    | `number`                      | Current zoom scale.                             |
+| `bgImage`      | `string \| undefined`         | URL to use as the zoomed background.            |
+| `containerRef` | `RefObject<HTMLDivElement>`   | Attach to the wrapper element.                  |
+| `imageRef`     | `RefObject<HTMLImageElement>` | Attach to the `<img>`.                          |
+| `lensRef`      | `RefObject<HTMLDivElement>`   | Attach to the lens element (lens/follow modes). |
+| `paneRef`      | `RefObject<HTMLDivElement>`   | Attach to the side-by-side pane.                |
+| `cursorRef`    | `RefObject<HTMLDivElement>`   | Attach to the side-by-side cursor dot.          |
+| `handlers`     | `object`                      | Spread on the container element.                |
+
 **Option highlights**
 
 | Option         | Type                                                                  | Default          |
@@ -345,57 +501,58 @@ const {
 
 Extends `UseImageMagnifyOptions` **plus**:
 
-| Prop             | Type                           | Default | Description                           |
-| ---------------- | ------------------------------ | ------- | ------------------------------------- |
-| `src`            | `string`                       | —       | Regular image URL.                    |
-| `alt`            | `string`                       | —       | Accessible label.                     |
-| `width`          | `number \| string`             | —       | Outer width. On mobile, forced to `100%`. |
-| `className`      | `string`                       | —       | Outer wrapper class.                  |
-| `style`          | `CSSProperties`                | —       | Outer wrapper style.                  |
-| `imageClassName` | `string`                       | —       | `<img>` class.                        |
-| `imageStyle`     | `CSSProperties`                | —       | `<img>` style.                        |
-| `lensClassName`  | `string`                       | —       | Lens element class.                   |
-| `lensStyle`      | `CSSProperties`                | —       | Lens element style.                   |
-| `paneClassName`  | `string`                       | —       | Side-by-side pane class.              |
-| `paneStyle`      | `CSSProperties`                | —       | Side-by-side pane style.              |
-| `paneWidth`      | `number \| string`             | `400`   | Pane width.                           |
-| `paneHeight`     | `number \| string`             | `400`   | Pane height.                          |
-| `lazy`           | `boolean`                      | —       | Use `loading="lazy"`.                 |
-| `imageProps`     | `ImgHTMLAttributes`            | —       | Extra props forwarded to the `<img>`. |
-| `onLoad`         | `ImgHTMLAttributes["onLoad"]`  | —       | Fired on image load.                  |
-| `onError`        | `ImgHTMLAttributes["onError"]` | —       | Fired on image error.                 |
+| Prop             | Type                           | Default | Description                                                                                                                               |
+| ---------------- | ------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`            | `string`                       | —       | Regular image URL.                                                                                                                        |
+| `alt`            | `string`                       | —       | Accessible label.                                                                                                                         |
+| `width`          | `number \| string`             | —       | Outer width. On mobile, forced to `100%`.                                                                                                 |
+| `className`      | `string`                       | —       | Outer wrapper class.                                                                                                                      |
+| `style`          | `CSSProperties`                | —       | Outer wrapper style.                                                                                                                      |
+| `imageClassName` | `string`                       | —       | `<img>` class.                                                                                                                            |
+| `imageStyle`     | `CSSProperties`                | —       | `<img>` style.                                                                                                                            |
+| `lensClassName`  | `string`                       | —       | Lens element class.                                                                                                                       |
+| `lensStyle`      | `CSSProperties`                | —       | Lens element style.                                                                                                                       |
+| `paneClassName`  | `string`                       | —       | Side-by-side pane class.                                                                                                                  |
+| `paneStyle`      | `CSSProperties`                | —       | Side-by-side pane style.                                                                                                                  |
+| `paneWidth`      | `number \| string`             | `400`   | Pane width.                                                                                                                               |
+| `paneHeight`     | `number \| string`             | `400`   | Pane height.                                                                                                                              |
+| `lazy`           | `boolean`                      | —       | Use `loading="lazy"` on the `<img>`.                                                                                                      |
+| `imageProps`     | `ImgHTMLAttributes`            | —       | Extra props forwarded to the `<img>`. Excludes `src`, `alt`, `style`, `className`, `onLoad`, `onError` (use the dedicated props instead). |
+| `onLoad`         | `ImgHTMLAttributes["onLoad"]`  | —       | Fired on image load.                                                                                                                      |
+| `onError`        | `ImgHTMLAttributes["onError"]` | —       | Fired on image error.                                                                                                                     |
 
 ### `ImageMagnifyGalleryProps`
 
 Extends `ImageMagnifyProps` **minus** `src` / `onLoad` / `onError`, plus:
 
-| Prop                          | Type                      | Default | Description                          |
-| ----------------------------- | ------------------------- | ------- | ------------------------------------ |
-| `images`                      | `string[]`                | —       | Image URLs.                          |
-| `alt`                         | `string`                  | —       | Alt text (shared).                   |
-| `activeIndex`                 | `number`                  | —       | Controlled index.                    |
-| `defaultIndex`                | `number`                  | `0`     | Initial index (uncontrolled).        |
-| `onIndexChange`               | `(index: number) => void` | —       | Fired when the active slide changes. |
-| `showArrows`                  | `boolean`                 | `true`  | Prev/next arrows.                    |
-| `showThumbnails`              | `boolean`                 | `true`  | Thumbnail strip.                     |
-| `showCounter`                 | `boolean`                 | `false` | "1 / N" counter overlay.             |
-| `loop`                        | `boolean`                 | `true`  | Infinite loop.                       |
-| `enableKeyboard`              | `boolean`                 | `true`  | Arrow-key navigation.                |
-| `preloadAdjacent`             | `boolean`                 | `true`  | Preload next/prev images.            |
-| `viewportClassName`           | `string`                  | —       | Main carousel viewport class.        |
-| `viewportStyle`               | `CSSProperties`           | —       | Main carousel viewport style.        |
-| `thumbnailContainerClassName` | `string`                  | —       | Thumbnail container class.           |
-| `thumbnailContainerStyle`     | `CSSProperties`           | —       | Thumbnail container style.           |
-| `thumbnailClassName`          | `string`                  | —       | Thumbnail button class.              |
-| `thumbnailActiveClassName`    | `string`                  | —       | Active thumbnail class.              |
-| `thumbnailStyle`              | `CSSProperties`           | —       | Thumbnail button style.              |
-| `thumbnailActiveStyle`        | `CSSProperties`           | —       | Active thumbnail style.              |
-| `arrowClassName`              | `string`                  | —       | Arrow button class.                  |
-| `arrowStyle`                  | `CSSProperties`           | —       | Arrow button style.                  |
-| `thumbnailSize`               | `number`                  | `80`    | Thumbnail size (px).                 |
-| `thumbnailGap`                | `number`                  | `8`     | Thumbnail gap (px).                  |
-| `prevArrow`                   | `ReactNode`               | —       | Custom previous arrow.               |
-| `nextArrow`                   | `ReactNode`               | —       | Custom next arrow.                   |
+| Prop                          | Type                      | Default | Description                                   |
+| ----------------------------- | ------------------------- | ------- | --------------------------------------------- |
+| `images`                      | `string[]`                | —       | Image URLs.                                   |
+| `alt`                         | `string`                  | —       | Alt text (shared; per-slide alt is appended). |
+| `activeIndex`                 | `number`                  | —       | Controlled index.                             |
+| `defaultIndex`                | `number`                  | `0`     | Initial index (uncontrolled).                 |
+| `onIndexChange`               | `(index: number) => void` | —       | Fired when the active slide changes.          |
+| `showArrows`                  | `boolean`                 | `true`  | Prev/next arrows.                             |
+| `showThumbnails`              | `boolean`                 | `true`  | Thumbnail strip.                              |
+| `showCounter`                 | `boolean`                 | `false` | "1 / N" counter overlay.                      |
+| `loop`                        | `boolean`                 | `true`  | Infinite loop.                                |
+| `enableKeyboard`              | `boolean`                 | `true`  | Arrow-key navigation.                         |
+| `preloadAdjacent`             | `boolean`                 | `true`  | Preload next/prev images (respects `loop`).   |
+| `viewportClassName`           | `string`                  | —       | Main carousel viewport class.                 |
+| `viewportStyle`               | `CSSProperties`           | —       | Main carousel viewport style.                 |
+| `swiperStyle`                 | `CSSProperties`           | —       | Style applied to the inner Swiper element.    |
+| `thumbnailContainerClassName` | `string`                  | —       | Thumbnail strip class.                        |
+| `thumbnailContainerStyle`     | `CSSProperties`           | —       | Thumbnail strip style.                        |
+| `thumbnailClassName`          | `string`                  | —       | Thumbnail button class.                       |
+| `thumbnailActiveClassName`    | `string`                  | —       | Added to the active thumbnail button.         |
+| `thumbnailStyle`              | `CSSProperties`           | —       | Thumbnail button style.                       |
+| `thumbnailActiveStyle`        | `CSSProperties`           | —       | Merged over `thumbnailStyle` when active.     |
+| `arrowClassName`              | `string`                  | —       | Arrow button class.                           |
+| `arrowStyle`                  | `CSSProperties`           | —       | Arrow button style.                           |
+| `thumbnailSize`               | `number`                  | `80`    | Thumbnail width/height (px).                  |
+| `thumbnailGap`                | `number`                  | `8`     | Thumbnail gap (px).                           |
+| `prevArrow`                   | `ReactNode`               | —       | Custom previous arrow.                        |
+| `nextArrow`                   | `ReactNode`               | —       | Custom next arrow.                            |
 
 ---
 
@@ -441,27 +598,38 @@ The gallery ships with inline defaults for arrows and thumbnails that you can ov
   alt="Product"
   thumbnailSize={64}
   thumbnailGap={12}
+  thumbnailContainerStyle={{ justifyContent: "center" }}
   thumbnailStyle={{ borderRadius: 8 }}
   thumbnailActiveStyle={{ borderColor: "#0af" }}
   arrowStyle={{ background: "#111", color: "#fff" }}
 />
 ```
 
+Because the gallery does not import any CSS from `swiper/css`, only the base Swiper runtime is used (no default arrow/thumbnail styles leak in). All visuals come from inline styles + your classes.
+
 ---
 
 ## Accessibility
 
 - Root gallery uses `role="region"`, `aria-roledescription="carousel"`, `aria-label`.
-- Each image container is `role="img"`, `tabIndex={0}`, `aria-label={alt}`.
+- Each image container is `role="img"` with `aria-label={alt}`. It is focusable (`tabIndex={0}`) **only when interaction is enabled** (`zoomType !== "none"` and not `disabled`).
 - Hidden `aria-live="polite"` region announces **"Image X of Y"** on slide change.
-- Keyboard support on the container:
-  - **← / → / ↑ / ↓** — move the zoom pointer.
-  - **+ / = / -** — zoom in/out (when `zoomType="wheel"`).
-  - **Enter / Space** — toggle zoom.
-  - **Esc** — reset zoom.
+- Thumbnails are `<button>` elements with `aria-label` and `aria-current="true"` for the active one; the strip is a `role="group"` labelled "Image thumbnails".
+- Arrow buttons get `aria-disabled` and `disabled` at the ends when `loop={false}`.
 - Disabled state exposes `aria-disabled`.
+- Swiper's `A11y` module is enabled for the main slider.
 - Custom arrows accept any `ReactNode`; default icons are `<svg aria-hidden="true">` with `aria-label` on the buttons.
 
+### Keyboard controls
+
+| Key               | Action                                            |
+| ----------------- | ------------------------------------------------- |
+| **← / → / ↑ / ↓** | Move the zoom pointer (image container).          |
+| **+ / = / -**     | Zoom in/out (when `zoomType="wheel"`).            |
+| **Enter / Space** | Toggle zoom.                                      |
+| **Esc**           | Reset zoom.                                       |
+| **← / →**         | Navigate slides (gallery, when `enableKeyboard`). |
+
 ---
 
 ## TypeScript
@@ -487,10 +655,12 @@ import type {
 
 ## Package Exports
 
-| Import path             | Contents                                                                                 |
-| ----------------------- | ---------------------------------------------------------------------------------------- |
-| `uix-image-magnify`     | `ImageMagnify`, `ImageMagnifyGallery`, `useImageMagnify`, `useImageSlider` + all types    |
-| `uix-image-magnify/ssr` | `ImageMagnifySSR`, `ImageMagnifyGallerySSR` (and their non-SSR re-exports)               |
+| Import path             | Contents                                                                                                                     |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `uix-image-magnify`     | `ImageMagnify`, `ImageMagnifyGallery`, `useImageMagnify`, `useImageSlider` + all types                                       |
+| `uix-image-magnify/ssr` | `ImageMagnifySSR`, `ImageMagnifyGallerySSR`, plus non-SSR re-exports (`ImageMagnify`, `ImageMagnifyGallery`) and their types |
+
+Both entry points are dual-published (ESM + CJS) with bundled TypeScript declarations.
 
 ---
 
@@ -503,7 +673,7 @@ Modern evergreen browsers (Chrome, Edge, Firefox, Safari). Requires:
 - Pointer Events
 - CSS `transform` / `background-position`
 
-SSR wrappers render plain `<img>` on the server for maximum compatibility.
+SSR wrappers render plain `<img>` on the server for maximum compatibility. The library uses React `>=17` and has no other runtime peer dependencies besides `swiper`.
 
 ---
 
@@ -513,6 +683,13 @@ MIT © uix-image-magnify contributors
 
 ---
 
-### Contributing
+## Contributing
+
+Issues and PRs are welcome. Before submitting, please run:
+
+```bash
+npm run typecheck
+npm run build
+```
 
-Issues and PRs welcome. Please run `npm run typecheck` and `npm run build` before submitting.
+Both must pass cleanly.

package/dist/{ImageMagnify-DssaU7jS.d.cts → ImageMagnifyGallery-Bw_SkDZq.d.cts}

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { CSSProperties, ImgHTMLAttributes } from 'react';
+import { CSSProperties, ImgHTMLAttributes, ReactNode } from 'react';
 
 type ZoomType = "hover" | "click" | "double-click" | "hold" | "wheel" | "none";
 type PanePosition = "left" | "right" | "top" | "bottom";
@@ -7,35 +7,20 @@ type LensShape = "circle" | "square";
 type MagnifyMode = "lens" | "side-by-side" | "inner" | "follow";
 type DragMode = "follow" | "pan";
 interface UseImageMagnifyOptions {
-    /** Base image URL (required when used standalone). */
     src?: string;
-    /** High-resolution image used for the zoomed view. Defaults to `src`. */
     zoomSrc?: string;
-    /** Magnification factor (2 = 200%). */
     zoomScale?: number;
-    /** Minimum scale for wheel/keyboard zoom. Default `1.5`. */
     minZoomScale?: number;
-    /** Maximum scale for wheel/keyboard zoom. Default `5`. */
     maxZoomScale?: number;
-    /** Interaction that activates zoom. */
     zoomType?: ZoomType;
-    /** How the zoomed content is displayed. */
     mode?: MagnifyMode;
-    /** Drag interaction for `inner` mode. */
     dragMode?: DragMode;
-    /** Where the side-by-side pane sits relative to the image. */
     panePosition?: PanePosition;
-    /** Diameter / side length of the lens in px. */
     lensSize?: number;
-    /** Lens shape. */
     lensShape?: LensShape;
-    /** Offset (both axes, px) for `mode="follow"`. */
     followOffset?: number;
-    /** Disable all interaction. */
     disabled?: boolean;
-    /** Preload the high-res image to avoid a flash. */
     zoomPreload?: boolean;
-    /** Reset zoom when the pointer leaves the container. */
     resetOnLeave?: boolean;
     onZoomStart?: () => void;
     onZoomEnd?: () => void;
@@ -79,10 +64,42 @@ interface ImageMagnifyProps extends UseImageMagnifyOptions {
     paneWidth?: number | string;
     paneHeight?: number | string;
     lazy?: boolean;
-    imageProps?: Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "style">;
+    imageProps?: Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "style" | "className" | "onLoad" | "onError">;
     onLoad?: ImgHTMLAttributes<HTMLImageElement>["onLoad"];
     onError?: ImgHTMLAttributes<HTMLImageElement>["onError"];
 }
 declare const ImageMagnify: React.ForwardRefExoticComponent<ImageMagnifyProps & React.RefAttributes<HTMLDivElement>>;
 
-export { type DragMode as D, type ImageMagnifyProps as I, type LensShape as L, type MagnifyMode as M, type PanePosition as P, type UseImageMagnifyOptions as U, type ZoomType as Z, ImageMagnify as a, useImageMagnify as u };
+interface ImageMagnifyGalleryProps extends Omit<ImageMagnifyProps, "src" | "onLoad" | "onError"> {
+    images: string[];
+    alt: string;
+    activeIndex?: number;
+    defaultIndex?: number;
+    onIndexChange?: (index: number) => void;
+    showArrows?: boolean;
+    showThumbnails?: boolean;
+    showCounter?: boolean;
+    loop?: boolean;
+    enableKeyboard?: boolean;
+    preloadAdjacent?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    viewportClassName?: string;
+    viewportStyle?: CSSProperties;
+    swiperStyle?: CSSProperties;
+    thumbnailContainerClassName?: string;
+    thumbnailContainerStyle?: CSSProperties;
+    thumbnailClassName?: string;
+    thumbnailActiveClassName?: string;
+    thumbnailStyle?: CSSProperties;
+    thumbnailActiveStyle?: CSSProperties;
+    arrowClassName?: string;
+    arrowStyle?: CSSProperties;
+    thumbnailSize?: number;
+    thumbnailGap?: number;
+    prevArrow?: ReactNode;
+    nextArrow?: ReactNode;
+}
+declare const ImageMagnifyGallery: React.ForwardRefExoticComponent<ImageMagnifyGalleryProps & React.RefAttributes<HTMLDivElement>>;
+
+export { type DragMode as D, ImageMagnify as I, type LensShape as L, type MagnifyMode as M, type PanePosition as P, type UseImageMagnifyOptions as U, type ZoomType as Z, ImageMagnifyGallery as a, type ImageMagnifyGalleryProps as b, type ImageMagnifyProps as c, useImageMagnify as u };