uix-image-magnify 0.2.1 → 0.2.4

package/README.md

@@ -0,0 +1,695 @@
+# uix-image-magnify
+
+**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), 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)
+
+---
+
+## Features
+
+- 🔍 **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 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
+
+---
+
+## Installation
+
+```bash
+npm install uix-image-magnify
+# or
+yarn add uix-image-magnify
+# or
+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
+
+```tsx
+import { ImageMagnify } from "uix-image-magnify";
+
+export default function ProductImage() {
+  return (
+    <ImageMagnify
+      src="/images/shoe.jpg"
+      zoomSrc="/images/shoe-large.jpg"
+      alt="Red running shoe"
+      width={500}
+      zoomScale={2.5}
+    />
+  );
+}
+```
+
+---
+
+## Single Image Magnifier
+
+`ImageMagnify` renders an image and zooms it on interaction. The high-res `zoomSrc` is used for the zoomed view while the regular `src` is shown normally — perfect for product photos.
+
+```tsx
+import { ImageMagnify } from "uix-image-magnify";
+
+<ImageMagnify
+  src="/thumb.jpg"
+  zoomSrc="/large.jpg"
+  alt="Product"
+  width="100%"
+  mode="side-by-side"
+  zoomType="hover"
+  zoomScale={3}
+  panePosition="right"
+  paneWidth={420}
+  paneHeight={420}
+  lensShape="circle"
+  lensSize={160}
+  lazy
+/>;
+```
+
+### Zoom modes
+
+| Mode           | Description                                                   |
+| -------------- | ------------------------------------------------------------- |
+| `lens`         | A circular/square lens follows the cursor over the image.     |
+| `side-by-side` | A fixed pane appears beside the image (classic Amazon style). |
+| `inner`        | The image itself scales and pans inside its own container.    |
+| `follow`       | A lens follows the cursor with an optional offset.            |
+
+### 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).             |
+
+> **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
+
+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. The image is **centered** the first time you zoom in.
+
+```tsx
+<ImageMagnify
+  src="/product.jpg"
+  alt="Product"
+  mode="inner"
+  dragMode="pan"
+  zoomType="click"
+  zoomScale={3}
+/>
+```
+
+### Wheel zoom
+
+```tsx
+<ImageMagnify
+  src="/product.jpg"
+  alt="Product"
+  zoomType="wheel"
+  zoomScale={2}
+  minZoomScale={1.5}
+  maxZoomScale={6}
+  onZoomChange={(s) => console.log("scale:", s)}
+/>
+```
+
+### 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 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";
+
+const images = [
+  "/images/shoe-1.jpg",
+  "/images/shoe-2.jpg",
+  "/images/shoe-3.jpg",
+];
+
+<ImageMagnifyGallery
+  images={images}
+  alt="Running shoe"
+  mode="side-by-side"
+  zoomType="hover"
+  zoomScale={2.5}
+  showArrows
+  showThumbnails
+  showCounter
+  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" }}
+/>
+```
+
+### Controlled gallery
+
+```tsx
+const [active, setActive] = useState(0);
+
+<ImageMagnifyGallery
+  images={images}
+  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
+<ImageMagnifyGallery
+  images={images}
+  alt="Product"
+  prevArrow={<span>←</span>}
+  nextArrow={<span>→</span>}
+  arrowClassName="my-arrow"
+  arrowStyle={{ background: "#000", color: "#fff" }}
+/>
+```
+
+Arrow buttons are automatically disabled (`disabled` + `aria-disabled`) at the ends when `loop={false}`.
+
+### Disable features
+
+```tsx
+<ImageMagnifyGallery
+  images={images}
+  alt="Product"
+  showArrows={false}
+  showThumbnails={false}
+  showCounter={false}
+  enableKeyboard={false}
+  preloadAdjacent={false}
+  loop={false}
+/>
+```
+
+### 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`, `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;
+}) {
+  return (
+    <ImageMagnifySSR
+      src={src}
+      alt={alt}
+      width={500}
+      mode="side-by-side"
+      zoomType="hover"
+    />
+  );
+}
+```
+
+```tsx
+import { ImageMagnifyGallerySSR } from "uix-image-magnify/ssr";
+
+<ImageMagnifyGallerySSR images={images} alt="Product" />;
+```
+
+### Option 2 — `next/dynamic` with `ssr: false`
+
+```tsx
+import dynamic from "next/dynamic";
+
+const ImageMagnify = dynamic(
+  () => import("uix-image-magnify").then((m) => m.ImageMagnify),
+  { ssr: false },
+);
+```
+
+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
+
+`uix-image-magnify/ssr` works anywhere `useEffect` runs. No additional config required.
+
+---
+
+## Hooks
+
+### `useImageSlider`
+
+A headless, SSR-safe slider state hook. No DOM, no browser globals.
+
+```tsx
+import { useImageSlider } from "uix-image-magnify";
+
+const { index, setIndex, prev, next, canPrev, canNext } = useImageSlider({
+  length: images.length,
+  defaultIndex: 0,
+  loop: true,
+  onIndexChange: (i) => console.log(i),
+});
+```
+
+**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.      |
+
+**Returns**
+
+| 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`
+
+Use the same engine behind `<ImageMagnify>` directly if you need a custom renderer. Returns refs + event handlers.
+
+```tsx
+import { useImageMagnify } from "uix-image-magnify";
+
+const {
+  isZoomed,
+  zoomScale,
+  bgImage,
+  containerRef,
+  imageRef,
+  lensRef,
+  paneRef,
+  cursorRef,
+  handlers,
+} = useImageMagnify({
+  src: "/thumb.jpg",
+  zoomSrc: "/large.jpg",
+  mode: "side-by-side",
+  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          |
+| -------------- | --------------------------------------------------------------------- | ---------------- |
+| `src`          | `string`                                                              | —                |
+| `zoomSrc`      | `string`                                                              | `src`            |
+| `zoomScale`    | `number`                                                              | `2`              |
+| `minZoomScale` | `number`                                                              | `1.5`            |
+| `maxZoomScale` | `number`                                                              | `5`              |
+| `zoomType`     | `"hover" \| "click" \| "double-click" \| "hold" \| "wheel" \| "none"` | `"hover"`        |
+| `mode`         | `"lens" \| "side-by-side" \| "inner" \| "follow"`                     | `"side-by-side"` |
+| `dragMode`     | `"follow" \| "pan"`                                                   | `"follow"`       |
+| `panePosition` | `"left" \| "right" \| "top" \| "bottom"`                              | `"right"`        |
+| `lensSize`     | `number`                                                              | `150`            |
+| `lensShape`    | `"circle" \| "square"`                                                | `"circle"`       |
+| `followOffset` | `number`                                                              | `0`              |
+| `zoomPreload`  | `boolean`                                                             | `true`           |
+| `disabled`     | `boolean`                                                             | `false`          |
+| `resetOnLeave` | `boolean`                                                             | `false`          |
+| `onZoomStart`  | `() => void`                                                          | —                |
+| `onZoomEnd`    | `() => void`                                                          | —                |
+| `onZoomChange` | `(scale: number) => void`                                             | —                |
+
+---
+
+## Props Reference
+
+### `ImageMagnifyProps`
+
+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"` 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; 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.                            |
+
+---
+
+## Styling
+
+Every part of the component is styleable via `className` / `style` props. The magnifier uses minimal inline styles and does not require any CSS import.
+
+```tsx
+<ImageMagnify
+  src="/a.jpg"
+  alt="Product"
+  width={480}
+  className="magnify-root"
+  imageClassName="magnify-image"
+  lensClassName="magnify-lens"
+  lensStyle={{ borderColor: "#111", boxShadow: "0 6px 20px rgba(0,0,0,.2)" }}
+  paneClassName="magnify-pane"
+  paneStyle={{ borderRadius: 12, border: "1px solid #eee" }}
+/>
+```
+
+```css
+.magnify-root {
+  border-radius: 12px;
+  overflow: hidden;
+  background: #f7f7f7;
+}
+
+.magnify-lens {
+  border-color: #111;
+}
+
+.magnify-pane {
+  background-color: #fafafa;
+}
+```
+
+The gallery ships with inline defaults for arrows and thumbnails that you can override fully:
+
+```tsx
+<ImageMagnifyGallery
+  images={images}
+  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"` 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.
+- 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
+
+The package is written in strict TypeScript and exports all prop and option types:
+
+```ts
+import type {
+  ImageMagnifyProps,
+  ImageMagnifyGalleryProps,
+  UseImageMagnifyOptions,
+  UseImageSliderOptions,
+  UseImageSliderReturn,
+  ZoomType,
+  PanePosition,
+  LensShape,
+  MagnifyMode,
+  DragMode,
+} from "uix-image-magnify";
+```
+
+---
+
+## Package 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.
+
+---
+
+## Browser Support
+
+Modern evergreen browsers (Chrome, Edge, Firefox, Safari). Requires:
+
+- `ResizeObserver`
+- `matchMedia`
+- Pointer Events
+- CSS `transform` / `background-position`
+
+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`.
+
+---
+
+## License
+
+MIT © uix-image-magnify contributors
+
+---
+
+## Contributing
+
+Issues and PRs are welcome. Before submitting, please run:
+
+```bash
+npm run typecheck
+npm run build
+```
+
+Both must pass cleanly.