uix-image-magnify 0.2.0 → 0.2.2

package/README.md

@@ -0,0 +1,518 @@
+# 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), a headless slider hook, and SSR-safe variants that prevent hydration mismatches in Next.js App Router, Remix, etc.
+
+---
+
+## 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 nav, ARIA roles, screen-reader live region
+- 🧠 **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
+
+---
+
+## 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.
+
+---
+
+## 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.            |
+
+> **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).          |
+
+> On touch devices, interaction behaves as tap-to-toggle regardless of `zoomType` (except `none`).
+
+### `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.
+
+```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)}
+/>
+```
+
+---
+
+## Product Gallery
+
+`ImageMagnifyGallery` combines a Swiper-powered slider with the magnifier. 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)}
+/>
+```
+
+### Controlled gallery
+
+```tsx
+const [active, setActive] = useState(0);
+
+<ImageMagnifyGallery
+  images={images}
+  alt="Product"
+  activeIndex={active}
+  onIndexChange={setActive}
+/>
+```
+
+### Custom arrows
+
+```tsx
+<ImageMagnifyGallery
+  images={images}
+  alt="Product"
+  prevArrow={<span>←</span>}
+  nextArrow={<span>→</span>}
+  arrowClassName="my-arrow"
+  arrowStyle={{ background: "#000", color: "#fff" }}
+/>
+```
+
+### Disable features
+
+```tsx
+<ImageMagnifyGallery
+  images={images}
+  alt="Product"
+  showArrows={false}
+  showThumbnails={false}
+  showCounter={false}
+  enableKeyboard={false}
+  preloadAdjacent={false}
+  loop={false}
+/>
+```
+
+---
+
+## 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:
+
+- `ImageMagnifySSR` — plain `<img>` on server + first client render, swaps to `<ImageMagnify>` after hydration.
+- `ImageMagnifyGallerySSR` — same approach for the gallery.
+
+### 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.
+
+### 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:** `{ index, setIndex, prev, next, canPrev, canNext }`.
+
+### `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,
+});
+```
+
+**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"`.                 |
+| `imageProps`     | `ImgHTMLAttributes`            | —       | Extra props forwarded to the `<img>`. |
+| `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.                   |
+
+---
+
+## 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}
+  thumbnailStyle={{ borderRadius: 8 }}
+  thumbnailActiveStyle={{ borderColor: "#0af" }}
+  arrowStyle={{ background: "#111", color: "#fff" }}
+/>
+```
+
+---
+
+## Accessibility
+
+- Root gallery uses `role="region"`, `aria-roledescription="carousel"`, `aria-label`.
+- Each image container is `role="img"`, `tabIndex={0}`, `aria-label={alt}`.
+- 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.
+- Disabled state exposes `aria-disabled`.
+- Custom arrows accept any `ReactNode`; default icons are `<svg aria-hidden="true">` with `aria-label` on the buttons.
+
+---
+
+## 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` (and their non-SSR re-exports)               |
+
+---
+
+## 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.
+
+---
+
+## License
+
+MIT © uix-image-magnify contributors
+
+---
+
+### Contributing
+
+Issues and PRs welcome. Please run `npm run typecheck` and `npm run build` before submitting.

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

@@ -67,7 +67,6 @@ declare function useImageMagnify(options?: UseImageMagnifyOptions): {
 interface ImageMagnifyProps extends UseImageMagnifyOptions {
     src: string;
     alt: string;
-    /** Rendered width of the image (height follows aspect ratio). */
     width?: number | string;
     className?: string;
     style?: CSSProperties;
@@ -77,10 +76,9 @@ interface ImageMagnifyProps extends UseImageMagnifyOptions {
     lensStyle?: CSSProperties;
     paneClassName?: string;
     paneStyle?: CSSProperties;
-    paneWidth?: number;
-    paneHeight?: number;
+    paneWidth?: number | string;
+    paneHeight?: number | string;
     lazy?: boolean;
-    /** Extra attributes forwarded to the underlying <img>. */
     imageProps?: Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "style">;
     onLoad?: ImgHTMLAttributes<HTMLImageElement>["onLoad"];
     onError?: ImgHTMLAttributes<HTMLImageElement>["onError"];

package/dist/{ImageMagnify-zNjM2jVN.d.ts → ImageMagnify-DssaU7jS.d.ts}

@@ -67,7 +67,6 @@ declare function useImageMagnify(options?: UseImageMagnifyOptions): {
 interface ImageMagnifyProps extends UseImageMagnifyOptions {
     src: string;
     alt: string;
-    /** Rendered width of the image (height follows aspect ratio). */
     width?: number | string;
     className?: string;
     style?: CSSProperties;
@@ -77,10 +76,9 @@ interface ImageMagnifyProps extends UseImageMagnifyOptions {
     lensStyle?: CSSProperties;
     paneClassName?: string;
     paneStyle?: CSSProperties;
-    paneWidth?: number;
-    paneHeight?: number;
+    paneWidth?: number | string;
+    paneHeight?: number | string;
     lazy?: boolean;
-    /** Extra attributes forwarded to the underlying <img>. */
     imageProps?: Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "style">;
     onLoad?: ImgHTMLAttributes<HTMLImageElement>["onLoad"];
     onError?: ImgHTMLAttributes<HTMLImageElement>["onError"];