@cjboco/cj-image-flip-previewer 1.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Doug Jones - Creative Juices, Bo. Co.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,260 @@
+# cj-image-flip-previewer
+
+[![npm version](https://img.shields.io/npm/v/cj-image-flip-previewer)](https://www.npmjs.com/package/cj-image-flip-previewer)
+[![license](https://img.shields.io/npm/l/cj-image-flip-previewer)](https://github.com/cjboco/cj-image-flip-previewer/blob/master/LICENSE)
+[![deploy](https://img.shields.io/github/actions/workflow/status/cjboco/cj-image-flip-previewer/deploy-demo.yml?label=demo)](https://cjboco.github.io/cj-image-flip-previewer/)
+
+A React component for interactive image previews. Zero dependencies beyond React 19+.
+
+**[Live Demo](https://cjboco.github.io/cj-image-flip-previewer/)**
+
+One component, two modes:
+- **`mode="position"`** — Image changes based on horizontal mouse/touch position (360-degree product views)
+- **`mode="hover"`** — Images auto-cycle on a timer when hovered (video thumbnail previews)
+
+## Install
+
+```bash
+npm install cj-image-flip-previewer
+```
+
+## Setup
+
+Import the stylesheet once in your app (e.g., in your root layout or entry file):
+
+```tsx
+import "cj-image-flip-previewer/styles.css";
+```
+
+---
+
+## Position Mode (default)
+
+Image changes based on where the mouse is horizontally within the container. Move left-to-right to cycle through all images.
+
+```tsx
+import { FlipPreviewer } from "cj-image-flip-previewer";
+
+<FlipPreviewer
+  width={320}
+  height={240}
+  images={[
+    { src: "/images/angle-1.jpg", alt: "Front" },
+    { src: "/images/angle-2.jpg", alt: "Side" },
+    { src: "/images/angle-3.jpg", alt: "Back" },
+    { src: "/images/angle-4.jpg", alt: "Other side" },
+  ]}
+/>
+```
+
+### With Links
+
+Each image can have its own link:
+
+```tsx
+<FlipPreviewer
+  width={320}
+  height={240}
+  images={[
+    { src: "/img1.jpg", href: "/products/1", title: "View product" },
+    { src: "/img2.jpg", href: "/products/2", target: "_blank", rel: "noopener noreferrer" },
+  ]}
+/>
+```
+
+---
+
+## Hover Mode
+
+Images auto-cycle on a timer when the mouse enters the container, like Netflix/YouTube thumbnail previews.
+
+```tsx
+<FlipPreviewer
+  mode="hover"
+  width={160}
+  height={110}
+  images={[
+    { src: "/images/frame-01.jpg" },
+    { src: "/images/frame-02.jpg" },
+    { src: "/images/frame-03.jpg" },
+    { src: "/images/frame-04.jpg" },
+  ]}
+/>
+```
+
+### Auto-Play
+
+Start cycling immediately without waiting for hover:
+
+```tsx
+<FlipPreviewer
+  mode="hover"
+  autoPlay
+  delay={300}
+  showProgress={false}
+  width={320}
+  height={240}
+  images={[
+    { src: "/frame1.jpg", href: "/watch/123" },
+    { src: "/frame2.jpg", href: "/watch/123" },
+    { src: "/frame3.jpg", href: "/watch/123" },
+  ]}
+/>
+```
+
+### Imperative Control
+
+Use a ref to programmatically start and pause the animation:
+
+```tsx
+import { useRef } from "react";
+import { FlipPreviewer, type FlipPreviewerRef } from "cj-image-flip-previewer";
+
+function ControlledPreviewer() {
+  const ref = useRef<FlipPreviewerRef>(null);
+
+  return (
+    <>
+      <FlipPreviewer
+        ref={ref}
+        mode="hover"
+        width={320}
+        height={240}
+        images={[
+          { src: "/frame1.jpg" },
+          { src: "/frame2.jpg" },
+          { src: "/frame3.jpg" },
+        ]}
+      />
+      <button onClick={() => ref.current?.start()}>Play</button>
+      <button onClick={() => ref.current?.pause()}>Pause</button>
+    </>
+  );
+}
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `mode` | `"position" \| "hover"` | `"position"` | How images cycle |
+| `images` | `FlipPreviewerImage[]` | *required* | Array of images |
+| `width` | `number \| string` | `"100%"` | Container width |
+| `height` | `number \| string` | `"100%"` | Container height |
+| `delay` | `number` | — | Ms between frames (hover mode only). Omit for max speed (requestAnimationFrame). |
+| `autoPlay` | `boolean` | `false` | Auto-start animation (hover mode only) |
+| `showProgress` | `boolean` | `true` | Show preload progress bar (hover mode only) |
+| `showCursor` | `boolean` | `true` | Show horizontal resize cursor (position mode only) |
+| `debug` | `boolean` | `false` | Show debug overlay (position mode only) |
+| `className` | `string` | — | Additional CSS class(es) |
+| `style` | `CSSProperties` | — | Additional inline styles |
+| `onIndexChange` | `(index: number) => void` | — | Called when the active image changes |
+| `onImagesLoaded` | `() => void` | — | Called when all images finish preloading (hover mode only) |
+| `ref` | `Ref<FlipPreviewerRef>` | — | Imperative handle for start/pause (hover mode only) |
+
+### FlipPreviewerImage
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `src` | `string` | Image source URL (required) |
+| `alt` | `string` | Alt text |
+| `href` | `string` | Link URL |
+| `title` | `string` | Link title |
+| `target` | `string` | Link target (e.g., `"_blank"`) |
+| `rel` | `string` | Link rel (e.g., `"noopener noreferrer"`) |
+
+### FlipPreviewerRef
+
+| Method | Description |
+|--------|-------------|
+| `start()` | Start the frame animation |
+| `pause()` | Pause and reset to the first frame |
+
+---
+
+## Styling
+
+### Default CSS
+
+The included stylesheet uses `@layer components`, which works both as standalone CSS and with Tailwind CSS v4+. Import it once in your app:
+
+```tsx
+import "cj-image-flip-previewer/styles.css";
+```
+
+### Using with Tailwind CSS
+
+Since the component styles are in the `components` layer, Tailwind utility classes automatically take priority — no `!important` needed. Just add classes via the `className` prop:
+
+```tsx
+<FlipPreviewer
+  className="rounded-lg shadow-md cursor-grab"
+  width={320}
+  height={240}
+  images={images}
+/>
+```
+
+If you prefer full Tailwind control and don't want the default stylesheet at all, simply skip the CSS import. The component applies its essential layout styles inline, so it will still function correctly. You can then style everything with utility classes.
+
+### CSS Custom Properties
+
+The stylesheet exposes CSS variables for common customizations. Override them in your own CSS or Tailwind's `globals.css`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--cj-flip-progress-height` | `4px` | Height of the preload progress bar |
+| `--cj-flip-progress-bg` | `rgba(0,0,0,0.3)` | Progress bar track background |
+| `--cj-flip-progress-color` | `#6bc4f7` | Progress bar fill color |
+| `--cj-flip-progress-speed` | `0.2s` | Progress bar transition speed |
+| `--cj-flip-debug-font-size` | `11px` | Debug overlay font size |
+| `--cj-flip-debug-bg` | `rgba(0,0,0,0.6)` | Debug overlay background |
+| `--cj-flip-debug-color` | `#fff` | Debug overlay text color |
+
+**Override globally:**
+
+```css
+:root {
+  --cj-flip-progress-color: hotpink;
+  --cj-flip-progress-height: 6px;
+}
+```
+
+**Override per instance:**
+
+```tsx
+<FlipPreviewer
+  style={{ '--cj-flip-progress-color': '#facc15' } as CSSProperties}
+  images={images}
+/>
+```
+
+### BEM Class Names
+
+For more targeted CSS overrides, all elements use BEM-style class names:
+
+```css
+.cj-flip-previewer { }
+.cj-flip-previewer__img { }
+.cj-flip-previewer__link { }
+.cj-flip-previewer__debug { }
+.cj-flip-previewer__progress { }
+.cj-flip-previewer__progress-bar { }
+```
+
+---
+
+## Requirements
+
+- React 19+
+- React DOM 19+
+
+## License
+
+BSD-3-Clause
+
+## Author
+
+Doug Jones — [Creative Juices, Bo. Co.](https://www.cjboco.com)

package/dist/index.cjs

@@ -0,0 +1,231 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FlipPreviewer: () => FlipPreviewer
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/FlipPreviewer.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+function FlipPreviewer({
+  mode = "position",
+  images,
+  width,
+  height,
+  fit = "cover",
+  delay,
+  autoPlay = false,
+  showProgress = true,
+  showCursor = true,
+  debug = false,
+  className,
+  style,
+  onIndexChange,
+  onImagesLoaded,
+  ref
+}) {
+  const containerRef = (0, import_react.useRef)(null);
+  const timerRef = (0, import_react.useRef)(null);
+  const [activeIndex, setActiveIndex] = (0, import_react.useState)(0);
+  const [debugInfo, setDebugInfo] = (0, import_react.useState)("");
+  const [loadedCount, setLoadedCount] = (0, import_react.useState)(0);
+  const [allLoaded, setAllLoaded] = (0, import_react.useState)(false);
+  const activeIndexRef = (0, import_react.useRef)(0);
+  const isPlayingRef = (0, import_react.useRef)(false);
+  (0, import_react.useEffect)(() => {
+    if (mode !== "hover" || images.length === 0) {
+      setAllLoaded(true);
+      return;
+    }
+    let loaded = 0;
+    setLoadedCount(0);
+    setAllLoaded(false);
+    const total = images.length;
+    images.forEach(({ src }) => {
+      const img = new Image();
+      img.onload = img.onerror = () => {
+        loaded++;
+        setLoadedCount(loaded);
+        if (loaded >= total) {
+          setAllLoaded(true);
+          onImagesLoaded?.();
+        }
+      };
+      img.src = src;
+    });
+  }, [mode, images, onImagesLoaded]);
+  const clearTimer = (0, import_react.useCallback)(() => {
+    if (timerRef.current !== null) {
+      if (delay != null) {
+        clearTimeout(timerRef.current);
+      } else {
+        cancelAnimationFrame(timerRef.current);
+      }
+      timerRef.current = null;
+    }
+  }, [delay]);
+  const advanceFrame = (0, import_react.useCallback)(() => {
+    if (!isPlayingRef.current) return;
+    if (images.length <= 1) return;
+    const next = activeIndexRef.current + 1 >= images.length ? 0 : activeIndexRef.current + 1;
+    activeIndexRef.current = next;
+    setActiveIndex(next);
+    onIndexChange?.(next);
+    if (delay != null) {
+      timerRef.current = setTimeout(advanceFrame, delay);
+    } else {
+      timerRef.current = requestAnimationFrame(advanceFrame);
+    }
+  }, [images.length, delay, onIndexChange]);
+  const startAnimation = (0, import_react.useCallback)(() => {
+    if (!allLoaded || images.length <= 1) return;
+    isPlayingRef.current = true;
+    clearTimer();
+    if (delay != null) {
+      timerRef.current = setTimeout(advanceFrame, delay);
+    } else {
+      timerRef.current = requestAnimationFrame(advanceFrame);
+    }
+  }, [allLoaded, images.length, delay, advanceFrame, clearTimer]);
+  const stopAnimation = (0, import_react.useCallback)(() => {
+    isPlayingRef.current = false;
+    clearTimer();
+    activeIndexRef.current = 0;
+    setActiveIndex(0);
+    onIndexChange?.(0);
+  }, [clearTimer, onIndexChange]);
+  (0, import_react.useEffect)(() => {
+    if (mode === "hover" && autoPlay && allLoaded) {
+      startAnimation();
+    }
+    return () => clearTimer();
+  }, [mode, autoPlay, allLoaded, startAnimation, clearTimer]);
+  (0, import_react.useImperativeHandle)(
+    ref,
+    () => ({
+      start: startAnimation,
+      pause: stopAnimation
+    }),
+    [startAnimation, stopAnimation]
+  );
+  const handleMouseEnter = (0, import_react.useCallback)(() => {
+    if (mode === "hover" && !autoPlay) {
+      startAnimation();
+    }
+  }, [mode, autoPlay, startAnimation]);
+  const handleMouseLeave = (0, import_react.useCallback)(() => {
+    if (mode === "hover" && !autoPlay) {
+      stopAnimation();
+    }
+  }, [mode, autoPlay, stopAnimation]);
+  const handlePointerMove = (0, import_react.useCallback)(
+    (e) => {
+      if (mode !== "position") return;
+      const container = containerRef.current;
+      if (!container || images.length === 0) return;
+      const rect = container.getBoundingClientRect();
+      const x = e.clientX - rect.left;
+      let pos = Math.floor(x / rect.width * images.length);
+      pos = Math.max(0, Math.min(pos, images.length - 1));
+      if (pos !== activeIndexRef.current) {
+        activeIndexRef.current = pos;
+        setActiveIndex(pos);
+        onIndexChange?.(pos);
+      }
+      if (debug) {
+        const y = e.clientY - rect.top;
+        setDebugInfo(
+          `x:${Math.round(x)}, y:${Math.round(y)}, img:${pos + 1}/${images.length}, w:${Math.round(rect.width)}, h:${Math.round(rect.height)}`
+        );
+      }
+    },
+    [mode, images.length, debug, onIndexChange]
+  );
+  (0, import_react.useEffect)(() => {
+    setActiveIndex(0);
+    activeIndexRef.current = 0;
+  }, [images]);
+  if (images.length === 0) return null;
+  const activeImage = images[activeIndex];
+  const hasLink = !!activeImage.href;
+  const containerStyle = {
+    position: "relative",
+    width: width ?? "100%",
+    height: height ?? "100%",
+    overflow: "hidden",
+    cursor: hasLink ? "pointer" : mode === "position" && showCursor ? "ew-resize" : "default",
+    ...style
+  };
+  const imgElement = /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "img",
+    {
+      src: activeImage.src,
+      alt: activeImage.alt ?? "",
+      className: "cj-flip-previewer__img",
+      style: { objectFit: fit },
+      draggable: false
+    }
+  );
+  const content = hasLink ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "a",
+    {
+      href: activeImage.href,
+      title: activeImage.title,
+      target: activeImage.target,
+      rel: activeImage.rel,
+      className: "cj-flip-previewer__link",
+      children: imgElement
+    }
+  ) : imgElement;
+  const progressPct = images.length > 0 ? loadedCount / images.length * 100 : 0;
+  return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: container tracks pointer position for image flipping
+    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+      "div",
+      {
+        ref: containerRef,
+        className: `cj-flip-previewer${className ? ` ${className}` : ""}`,
+        style: containerStyle,
+        onPointerMove: handlePointerMove,
+        onMouseEnter: handleMouseEnter,
+        onMouseLeave: handleMouseLeave,
+        children: [
+          content,
+          mode === "hover" && showProgress && !allLoaded && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "cj-flip-previewer__progress", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            "div",
+            {
+              className: "cj-flip-previewer__progress-bar",
+              style: { width: `${progressPct}%` }
+            }
+          ) }),
+          mode === "position" && debug && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "cj-flip-previewer__debug", children: debugInfo })
+        ]
+      }
+    )
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FlipPreviewer
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/FlipPreviewer.tsx"],"sourcesContent":["export { FlipPreviewer } from \"./FlipPreviewer\";\nexport type {\n  FlipPreviewerProps,\n  FlipPreviewerImage,\n  FlipPreviewerRef,\n} from \"./FlipPreviewer\";\n","import {\n\ttype CSSProperties,\n\ttype Ref,\n\tuseCallback,\n\tuseEffect,\n\tuseImperativeHandle,\n\tuseRef,\n\tuseState,\n} from \"react\";\n\nexport interface FlipPreviewerImage {\n\t/** Image source URL */\n\tsrc: string;\n\t/** Alt text for the image */\n\talt?: string;\n\t/** Optional link URL — clicking the image navigates here */\n\thref?: string;\n\t/** Link title attribute */\n\ttitle?: string;\n\t/** Link target attribute (e.g., \"_blank\") */\n\ttarget?: string;\n\t/** Link rel attribute (e.g., \"noopener noreferrer\") */\n\trel?: string;\n}\n\nexport interface FlipPreviewerRef {\n\t/** Start the hover animation (only applies in \"hover\" mode) */\n\tstart: () => void;\n\t/** Pause the animation and reset to the first frame (only applies in \"hover\" mode) */\n\tpause: () => void;\n}\n\nexport interface FlipPreviewerProps {\n\t/**\n\t * How images cycle:\n\t * - `\"position\"` — image changes based on horizontal mouse/touch position (default)\n\t * - `\"hover\"` — images auto-cycle on a timer when hovered\n\t */\n\tmode?: \"position\" | \"hover\";\n\t/** Array of images to flip through */\n\timages: FlipPreviewerImage[];\n\t/** Width of the component (CSS value). Omit to fill parent at 100%. */\n\twidth?: number | string;\n\t/** Height of the component (CSS value). Omit to fill parent at 100%. */\n\theight?: number | string;\n\t/**\n\t * How images fit within the container:\n\t * - `\"cover\"` — image covers the entire container, may crop (default)\n\t * - `\"contain\"` — image fits entirely within the container, may letterbox\n\t */\n\tfit?: \"cover\" | \"contain\";\n\t/** Delay in ms between frame transitions — only used in \"hover\" mode. Omit for max speed (requestAnimationFrame). */\n\tdelay?: number;\n\t/** Start animating automatically without hover — only used in \"hover\" mode (default: false) */\n\tautoPlay?: boolean;\n\t/** Show a progress bar while images preload — only used in \"hover\" mode (default: true) */\n\tshowProgress?: boolean;\n\t/** Show a horizontal resize cursor when in \"position\" mode (default: true) */\n\tshowCursor?: boolean;\n\t/** Show debug overlay with mouse coordinates and position info — only used in \"position\" mode */\n\tdebug?: boolean;\n\t/** Additional CSS class name(s) for the container */\n\tclassName?: string;\n\t/** Additional inline styles for the container */\n\tstyle?: CSSProperties;\n\t/** Callback fired when the active image index changes */\n\tonIndexChange?: (index: number) => void;\n\t/** Callback fired when all images have finished preloading — only used in \"hover\" mode */\n\tonImagesLoaded?: () => void;\n\t/** Imperative handle ref for start/pause control in \"hover\" mode */\n\tref?: Ref<FlipPreviewerRef>;\n}\n\nexport function FlipPreviewer({\n\tmode = \"position\",\n\timages,\n\twidth,\n\theight,\n\tfit = \"cover\",\n\tdelay,\n\tautoPlay = false,\n\tshowProgress = true,\n\tshowCursor = true,\n\tdebug = false,\n\tclassName,\n\tstyle,\n\tonIndexChange,\n\tonImagesLoaded,\n\tref,\n}: FlipPreviewerProps) {\n\tconst containerRef = useRef<HTMLDivElement>(null);\n\tconst timerRef = useRef<ReturnType<typeof setTimeout> | number | null>(null);\n\n\tconst [activeIndex, setActiveIndex] = useState(0);\n\tconst [debugInfo, setDebugInfo] = useState(\"\");\n\tconst [loadedCount, setLoadedCount] = useState(0);\n\tconst [allLoaded, setAllLoaded] = useState(false);\n\n\tconst activeIndexRef = useRef(0);\n\tconst isPlayingRef = useRef(false);\n\n\t// ── Preload images (hover mode) ──────────────────────────────\n\tuseEffect(() => {\n\t\tif (mode !== \"hover\" || images.length === 0) {\n\t\t\tsetAllLoaded(true);\n\t\t\treturn;\n\t\t}\n\n\t\tlet loaded = 0;\n\t\tsetLoadedCount(0);\n\t\tsetAllLoaded(false);\n\n\t\tconst total = images.length;\n\t\timages.forEach(({ src }) => {\n\t\t\tconst img = new Image();\n\t\t\timg.onload = img.onerror = () => {\n\t\t\t\tloaded++;\n\t\t\t\tsetLoadedCount(loaded);\n\t\t\t\tif (loaded >= total) {\n\t\t\t\t\tsetAllLoaded(true);\n\t\t\t\t\tonImagesLoaded?.();\n\t\t\t\t}\n\t\t\t};\n\t\t\timg.src = src;\n\t\t});\n\t}, [mode, images, onImagesLoaded]);\n\n\t// ── Hover mode: animation ────────────────────────────────────\n\tconst clearTimer = useCallback(() => {\n\t\tif (timerRef.current !== null) {\n\t\t\tif (delay != null) {\n\t\t\t\tclearTimeout(timerRef.current as ReturnType<typeof setTimeout>);\n\t\t\t} else {\n\t\t\t\tcancelAnimationFrame(timerRef.current as number);\n\t\t\t}\n\t\t\ttimerRef.current = null;\n\t\t}\n\t}, [delay]);\n\n\tconst advanceFrame = useCallback(() => {\n\t\tif (!isPlayingRef.current) return;\n\t\tif (images.length <= 1) return;\n\n\t\tconst next =\n\t\t\tactiveIndexRef.current + 1 >= images.length\n\t\t\t\t? 0\n\t\t\t\t: activeIndexRef.current + 1;\n\n\t\tactiveIndexRef.current = next;\n\t\tsetActiveIndex(next);\n\t\tonIndexChange?.(next);\n\n\t\tif (delay != null) {\n\t\t\ttimerRef.current = setTimeout(advanceFrame, delay);\n\t\t} else {\n\t\t\ttimerRef.current = requestAnimationFrame(advanceFrame);\n\t\t}\n\t}, [images.length, delay, onIndexChange]);\n\n\tconst startAnimation = useCallback(() => {\n\t\tif (!allLoaded || images.length <= 1) return;\n\t\tisPlayingRef.current = true;\n\t\tclearTimer();\n\t\tif (delay != null) {\n\t\t\ttimerRef.current = setTimeout(advanceFrame, delay);\n\t\t} else {\n\t\t\ttimerRef.current = requestAnimationFrame(advanceFrame);\n\t\t}\n\t}, [allLoaded, images.length, delay, advanceFrame, clearTimer]);\n\n\tconst stopAnimation = useCallback(() => {\n\t\tisPlayingRef.current = false;\n\t\tclearTimer();\n\t\tactiveIndexRef.current = 0;\n\t\tsetActiveIndex(0);\n\t\tonIndexChange?.(0);\n\t}, [clearTimer, onIndexChange]);\n\n\t// Auto-play on mount if enabled (hover mode)\n\tuseEffect(() => {\n\t\tif (mode === \"hover\" && autoPlay && allLoaded) {\n\t\t\tstartAnimation();\n\t\t}\n\t\treturn () => clearTimer();\n\t}, [mode, autoPlay, allLoaded, startAnimation, clearTimer]);\n\n\t// Expose start/pause via ref (hover mode)\n\tuseImperativeHandle(\n\t\tref,\n\t\t() => ({\n\t\t\tstart: startAnimation,\n\t\t\tpause: stopAnimation,\n\t\t}),\n\t\t[startAnimation, stopAnimation],\n\t);\n\n\tconst handleMouseEnter = useCallback(() => {\n\t\tif (mode === \"hover\" && !autoPlay) {\n\t\t\tstartAnimation();\n\t\t}\n\t}, [mode, autoPlay, startAnimation]);\n\n\tconst handleMouseLeave = useCallback(() => {\n\t\tif (mode === \"hover\" && !autoPlay) {\n\t\t\tstopAnimation();\n\t\t}\n\t}, [mode, autoPlay, stopAnimation]);\n\n\t// ── Position mode: mouse-position-based ──────────────────────\n\tconst handlePointerMove = useCallback(\n\t\t(e: React.PointerEvent<HTMLDivElement>) => {\n\t\t\tif (mode !== \"position\") return;\n\n\t\t\tconst container = containerRef.current;\n\t\t\tif (!container || images.length === 0) return;\n\n\t\t\tconst rect = container.getBoundingClientRect();\n\t\t\tconst x = e.clientX - rect.left;\n\t\t\tlet pos = Math.floor((x / rect.width) * images.length);\n\t\t\tpos = Math.max(0, Math.min(pos, images.length - 1));\n\n\t\t\tif (pos !== activeIndexRef.current) {\n\t\t\t\tactiveIndexRef.current = pos;\n\t\t\t\tsetActiveIndex(pos);\n\t\t\t\tonIndexChange?.(pos);\n\t\t\t}\n\n\t\t\tif (debug) {\n\t\t\t\tconst y = e.clientY - rect.top;\n\t\t\t\tsetDebugInfo(\n\t\t\t\t\t`x:${Math.round(x)}, y:${Math.round(y)}, img:${pos + 1}/${images.length}, w:${Math.round(rect.width)}, h:${Math.round(rect.height)}`,\n\t\t\t\t);\n\t\t\t}\n\t\t},\n\t\t[mode, images.length, debug, onIndexChange],\n\t);\n\n\t// Reset index if images change\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: intentional trigger when images change\n\tuseEffect(() => {\n\t\tsetActiveIndex(0);\n\t\tactiveIndexRef.current = 0;\n\t}, [images]);\n\n\t// ── Render ───────────────────────────────────────────────────\n\tif (images.length === 0) return null;\n\n\tconst activeImage = images[activeIndex];\n\tconst hasLink = !!activeImage.href;\n\n\tconst containerStyle: CSSProperties = {\n\t\tposition: \"relative\",\n\t\twidth: width ?? \"100%\",\n\t\theight: height ?? \"100%\",\n\t\toverflow: \"hidden\",\n\t\tcursor: hasLink\n\t\t\t? \"pointer\"\n\t\t\t: mode === \"position\" && showCursor\n\t\t\t\t? \"ew-resize\"\n\t\t\t\t: \"default\",\n\t\t...style,\n\t};\n\n\tconst imgElement = (\n\t\t<img\n\t\t\tsrc={activeImage.src}\n\t\t\talt={activeImage.alt ?? \"\"}\n\t\t\tclassName=\"cj-flip-previewer__img\"\n\t\t\tstyle={{ objectFit: fit }}\n\t\t\tdraggable={false}\n\t\t/>\n\t);\n\n\tconst content = hasLink ? (\n\t\t<a\n\t\t\thref={activeImage.href}\n\t\t\ttitle={activeImage.title}\n\t\t\ttarget={activeImage.target}\n\t\t\trel={activeImage.rel}\n\t\t\tclassName=\"cj-flip-previewer__link\"\n\t\t>\n\t\t\t{imgElement}\n\t\t</a>\n\t) : (\n\t\timgElement\n\t);\n\n\tconst progressPct =\n\t\timages.length > 0 ? (loadedCount / images.length) * 100 : 0;\n\n\treturn (\n\t\t// biome-ignore lint/a11y/noStaticElementInteractions: container tracks pointer position for image flipping\n\t\t<div\n\t\t\tref={containerRef}\n\t\t\tclassName={`cj-flip-previewer${className ? ` ${className}` : \"\"}`}\n\t\t\tstyle={containerStyle}\n\t\t\tonPointerMove={handlePointerMove}\n\t\t\tonMouseEnter={handleMouseEnter}\n\t\t\tonMouseLeave={handleMouseLeave}\n\t\t>\n\t\t\t{content}\n\n\t\t\t{mode === \"hover\" && showProgress && !allLoaded && (\n\t\t\t\t<div className=\"cj-flip-previewer__progress\">\n\t\t\t\t\t<div\n\t\t\t\t\t\tclassName=\"cj-flip-previewer__progress-bar\"\n\t\t\t\t\t\tstyle={{ width: `${progressPct}%` }}\n\t\t\t\t\t/>\n\t\t\t\t</div>\n\t\t\t)}\n\n\t\t\t{mode === \"position\" && debug && (\n\t\t\t\t<div className=\"cj-flip-previewer__debug\">{debugInfo}</div>\n\t\t\t)}\n\t\t</div>\n\t);\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,66 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties, Ref } from 'react';
+
+interface FlipPreviewerImage {
+    /** Image source URL */
+    src: string;
+    /** Alt text for the image */
+    alt?: string;
+    /** Optional link URL — clicking the image navigates here */
+    href?: string;
+    /** Link title attribute */
+    title?: string;
+    /** Link target attribute (e.g., "_blank") */
+    target?: string;
+    /** Link rel attribute (e.g., "noopener noreferrer") */
+    rel?: string;
+}
+interface FlipPreviewerRef {
+    /** Start the hover animation (only applies in "hover" mode) */
+    start: () => void;
+    /** Pause the animation and reset to the first frame (only applies in "hover" mode) */
+    pause: () => void;
+}
+interface FlipPreviewerProps {
+    /**
+     * How images cycle:
+     * - `"position"` — image changes based on horizontal mouse/touch position (default)
+     * - `"hover"` — images auto-cycle on a timer when hovered
+     */
+    mode?: "position" | "hover";
+    /** Array of images to flip through */
+    images: FlipPreviewerImage[];
+    /** Width of the component (CSS value). Omit to fill parent at 100%. */
+    width?: number | string;
+    /** Height of the component (CSS value). Omit to fill parent at 100%. */
+    height?: number | string;
+    /**
+     * How images fit within the container:
+     * - `"cover"` — image covers the entire container, may crop (default)
+     * - `"contain"` — image fits entirely within the container, may letterbox
+     */
+    fit?: "cover" | "contain";
+    /** Delay in ms between frame transitions — only used in "hover" mode. Omit for max speed (requestAnimationFrame). */
+    delay?: number;
+    /** Start animating automatically without hover — only used in "hover" mode (default: false) */
+    autoPlay?: boolean;
+    /** Show a progress bar while images preload — only used in "hover" mode (default: true) */
+    showProgress?: boolean;
+    /** Show a horizontal resize cursor when in "position" mode (default: true) */
+    showCursor?: boolean;
+    /** Show debug overlay with mouse coordinates and position info — only used in "position" mode */
+    debug?: boolean;
+    /** Additional CSS class name(s) for the container */
+    className?: string;
+    /** Additional inline styles for the container */
+    style?: CSSProperties;
+    /** Callback fired when the active image index changes */
+    onIndexChange?: (index: number) => void;
+    /** Callback fired when all images have finished preloading — only used in "hover" mode */
+    onImagesLoaded?: () => void;
+    /** Imperative handle ref for start/pause control in "hover" mode */
+    ref?: Ref<FlipPreviewerRef>;
+}
+declare function FlipPreviewer({ mode, images, width, height, fit, delay, autoPlay, showProgress, showCursor, debug, className, style, onIndexChange, onImagesLoaded, ref, }: FlipPreviewerProps): react_jsx_runtime.JSX.Element | null;
+
+export { FlipPreviewer, type FlipPreviewerImage, type FlipPreviewerProps, type FlipPreviewerRef };

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties, Ref } from 'react';
+
+interface FlipPreviewerImage {
+    /** Image source URL */
+    src: string;
+    /** Alt text for the image */
+    alt?: string;
+    /** Optional link URL — clicking the image navigates here */
+    href?: string;
+    /** Link title attribute */
+    title?: string;
+    /** Link target attribute (e.g., "_blank") */
+    target?: string;
+    /** Link rel attribute (e.g., "noopener noreferrer") */
+    rel?: string;
+}
+interface FlipPreviewerRef {
+    /** Start the hover animation (only applies in "hover" mode) */
+    start: () => void;
+    /** Pause the animation and reset to the first frame (only applies in "hover" mode) */
+    pause: () => void;
+}
+interface FlipPreviewerProps {
+    /**
+     * How images cycle:
+     * - `"position"` — image changes based on horizontal mouse/touch position (default)
+     * - `"hover"` — images auto-cycle on a timer when hovered
+     */
+    mode?: "position" | "hover";
+    /** Array of images to flip through */
+    images: FlipPreviewerImage[];
+    /** Width of the component (CSS value). Omit to fill parent at 100%. */
+    width?: number | string;
+    /** Height of the component (CSS value). Omit to fill parent at 100%. */
+    height?: number | string;
+    /**
+     * How images fit within the container:
+     * - `"cover"` — image covers the entire container, may crop (default)
+     * - `"contain"` — image fits entirely within the container, may letterbox
+     */
+    fit?: "cover" | "contain";
+    /** Delay in ms between frame transitions — only used in "hover" mode. Omit for max speed (requestAnimationFrame). */
+    delay?: number;
+    /** Start animating automatically without hover — only used in "hover" mode (default: false) */
+    autoPlay?: boolean;
+    /** Show a progress bar while images preload — only used in "hover" mode (default: true) */
+    showProgress?: boolean;
+    /** Show a horizontal resize cursor when in "position" mode (default: true) */
+    showCursor?: boolean;
+    /** Show debug overlay with mouse coordinates and position info — only used in "position" mode */
+    debug?: boolean;
+    /** Additional CSS class name(s) for the container */
+    className?: string;
+    /** Additional inline styles for the container */
+    style?: CSSProperties;
+    /** Callback fired when the active image index changes */
+    onIndexChange?: (index: number) => void;
+    /** Callback fired when all images have finished preloading — only used in "hover" mode */
+    onImagesLoaded?: () => void;
+    /** Imperative handle ref for start/pause control in "hover" mode */
+    ref?: Ref<FlipPreviewerRef>;
+}
+declare function FlipPreviewer({ mode, images, width, height, fit, delay, autoPlay, showProgress, showCursor, debug, className, style, onIndexChange, onImagesLoaded, ref, }: FlipPreviewerProps): react_jsx_runtime.JSX.Element | null;
+
+export { FlipPreviewer, type FlipPreviewerImage, type FlipPreviewerProps, type FlipPreviewerRef };

package/dist/index.js

@@ -0,0 +1,210 @@
+// src/FlipPreviewer.tsx
+import {
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState
+} from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+function FlipPreviewer({
+  mode = "position",
+  images,
+  width,
+  height,
+  fit = "cover",
+  delay,
+  autoPlay = false,
+  showProgress = true,
+  showCursor = true,
+  debug = false,
+  className,
+  style,
+  onIndexChange,
+  onImagesLoaded,
+  ref
+}) {
+  const containerRef = useRef(null);
+  const timerRef = useRef(null);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const [debugInfo, setDebugInfo] = useState("");
+  const [loadedCount, setLoadedCount] = useState(0);
+  const [allLoaded, setAllLoaded] = useState(false);
+  const activeIndexRef = useRef(0);
+  const isPlayingRef = useRef(false);
+  useEffect(() => {
+    if (mode !== "hover" || images.length === 0) {
+      setAllLoaded(true);
+      return;
+    }
+    let loaded = 0;
+    setLoadedCount(0);
+    setAllLoaded(false);
+    const total = images.length;
+    images.forEach(({ src }) => {
+      const img = new Image();
+      img.onload = img.onerror = () => {
+        loaded++;
+        setLoadedCount(loaded);
+        if (loaded >= total) {
+          setAllLoaded(true);
+          onImagesLoaded?.();
+        }
+      };
+      img.src = src;
+    });
+  }, [mode, images, onImagesLoaded]);
+  const clearTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      if (delay != null) {
+        clearTimeout(timerRef.current);
+      } else {
+        cancelAnimationFrame(timerRef.current);
+      }
+      timerRef.current = null;
+    }
+  }, [delay]);
+  const advanceFrame = useCallback(() => {
+    if (!isPlayingRef.current) return;
+    if (images.length <= 1) return;
+    const next = activeIndexRef.current + 1 >= images.length ? 0 : activeIndexRef.current + 1;
+    activeIndexRef.current = next;
+    setActiveIndex(next);
+    onIndexChange?.(next);
+    if (delay != null) {
+      timerRef.current = setTimeout(advanceFrame, delay);
+    } else {
+      timerRef.current = requestAnimationFrame(advanceFrame);
+    }
+  }, [images.length, delay, onIndexChange]);
+  const startAnimation = useCallback(() => {
+    if (!allLoaded || images.length <= 1) return;
+    isPlayingRef.current = true;
+    clearTimer();
+    if (delay != null) {
+      timerRef.current = setTimeout(advanceFrame, delay);
+    } else {
+      timerRef.current = requestAnimationFrame(advanceFrame);
+    }
+  }, [allLoaded, images.length, delay, advanceFrame, clearTimer]);
+  const stopAnimation = useCallback(() => {
+    isPlayingRef.current = false;
+    clearTimer();
+    activeIndexRef.current = 0;
+    setActiveIndex(0);
+    onIndexChange?.(0);
+  }, [clearTimer, onIndexChange]);
+  useEffect(() => {
+    if (mode === "hover" && autoPlay && allLoaded) {
+      startAnimation();
+    }
+    return () => clearTimer();
+  }, [mode, autoPlay, allLoaded, startAnimation, clearTimer]);
+  useImperativeHandle(
+    ref,
+    () => ({
+      start: startAnimation,
+      pause: stopAnimation
+    }),
+    [startAnimation, stopAnimation]
+  );
+  const handleMouseEnter = useCallback(() => {
+    if (mode === "hover" && !autoPlay) {
+      startAnimation();
+    }
+  }, [mode, autoPlay, startAnimation]);
+  const handleMouseLeave = useCallback(() => {
+    if (mode === "hover" && !autoPlay) {
+      stopAnimation();
+    }
+  }, [mode, autoPlay, stopAnimation]);
+  const handlePointerMove = useCallback(
+    (e) => {
+      if (mode !== "position") return;
+      const container = containerRef.current;
+      if (!container || images.length === 0) return;
+      const rect = container.getBoundingClientRect();
+      const x = e.clientX - rect.left;
+      let pos = Math.floor(x / rect.width * images.length);
+      pos = Math.max(0, Math.min(pos, images.length - 1));
+      if (pos !== activeIndexRef.current) {
+        activeIndexRef.current = pos;
+        setActiveIndex(pos);
+        onIndexChange?.(pos);
+      }
+      if (debug) {
+        const y = e.clientY - rect.top;
+        setDebugInfo(
+          `x:${Math.round(x)}, y:${Math.round(y)}, img:${pos + 1}/${images.length}, w:${Math.round(rect.width)}, h:${Math.round(rect.height)}`
+        );
+      }
+    },
+    [mode, images.length, debug, onIndexChange]
+  );
+  useEffect(() => {
+    setActiveIndex(0);
+    activeIndexRef.current = 0;
+  }, [images]);
+  if (images.length === 0) return null;
+  const activeImage = images[activeIndex];
+  const hasLink = !!activeImage.href;
+  const containerStyle = {
+    position: "relative",
+    width: width ?? "100%",
+    height: height ?? "100%",
+    overflow: "hidden",
+    cursor: hasLink ? "pointer" : mode === "position" && showCursor ? "ew-resize" : "default",
+    ...style
+  };
+  const imgElement = /* @__PURE__ */ jsx(
+    "img",
+    {
+      src: activeImage.src,
+      alt: activeImage.alt ?? "",
+      className: "cj-flip-previewer__img",
+      style: { objectFit: fit },
+      draggable: false
+    }
+  );
+  const content = hasLink ? /* @__PURE__ */ jsx(
+    "a",
+    {
+      href: activeImage.href,
+      title: activeImage.title,
+      target: activeImage.target,
+      rel: activeImage.rel,
+      className: "cj-flip-previewer__link",
+      children: imgElement
+    }
+  ) : imgElement;
+  const progressPct = images.length > 0 ? loadedCount / images.length * 100 : 0;
+  return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: container tracks pointer position for image flipping
+    /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref: containerRef,
+        className: `cj-flip-previewer${className ? ` ${className}` : ""}`,
+        style: containerStyle,
+        onPointerMove: handlePointerMove,
+        onMouseEnter: handleMouseEnter,
+        onMouseLeave: handleMouseLeave,
+        children: [
+          content,
+          mode === "hover" && showProgress && !allLoaded && /* @__PURE__ */ jsx("div", { className: "cj-flip-previewer__progress", children: /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: "cj-flip-previewer__progress-bar",
+              style: { width: `${progressPct}%` }
+            }
+          ) }),
+          mode === "position" && debug && /* @__PURE__ */ jsx("div", { className: "cj-flip-previewer__debug", children: debugInfo })
+        ]
+      }
+    )
+  );
+}
+export {
+  FlipPreviewer
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/FlipPreviewer.tsx"],"sourcesContent":["import {\n\ttype CSSProperties,\n\ttype Ref,\n\tuseCallback,\n\tuseEffect,\n\tuseImperativeHandle,\n\tuseRef,\n\tuseState,\n} from \"react\";\n\nexport interface FlipPreviewerImage {\n\t/** Image source URL */\n\tsrc: string;\n\t/** Alt text for the image */\n\talt?: string;\n\t/** Optional link URL — clicking the image navigates here */\n\thref?: string;\n\t/** Link title attribute */\n\ttitle?: string;\n\t/** Link target attribute (e.g., \"_blank\") */\n\ttarget?: string;\n\t/** Link rel attribute (e.g., \"noopener noreferrer\") */\n\trel?: string;\n}\n\nexport interface FlipPreviewerRef {\n\t/** Start the hover animation (only applies in \"hover\" mode) */\n\tstart: () => void;\n\t/** Pause the animation and reset to the first frame (only applies in \"hover\" mode) */\n\tpause: () => void;\n}\n\nexport interface FlipPreviewerProps {\n\t/**\n\t * How images cycle:\n\t * - `\"position\"` — image changes based on horizontal mouse/touch position (default)\n\t * - `\"hover\"` — images auto-cycle on a timer when hovered\n\t */\n\tmode?: \"position\" | \"hover\";\n\t/** Array of images to flip through */\n\timages: FlipPreviewerImage[];\n\t/** Width of the component (CSS value). Omit to fill parent at 100%. */\n\twidth?: number | string;\n\t/** Height of the component (CSS value). Omit to fill parent at 100%. */\n\theight?: number | string;\n\t/**\n\t * How images fit within the container:\n\t * - `\"cover\"` — image covers the entire container, may crop (default)\n\t * - `\"contain\"` — image fits entirely within the container, may letterbox\n\t */\n\tfit?: \"cover\" | \"contain\";\n\t/** Delay in ms between frame transitions — only used in \"hover\" mode. Omit for max speed (requestAnimationFrame). */\n\tdelay?: number;\n\t/** Start animating automatically without hover — only used in \"hover\" mode (default: false) */\n\tautoPlay?: boolean;\n\t/** Show a progress bar while images preload — only used in \"hover\" mode (default: true) */\n\tshowProgress?: boolean;\n\t/** Show a horizontal resize cursor when in \"position\" mode (default: true) */\n\tshowCursor?: boolean;\n\t/** Show debug overlay with mouse coordinates and position info — only used in \"position\" mode */\n\tdebug?: boolean;\n\t/** Additional CSS class name(s) for the container */\n\tclassName?: string;\n\t/** Additional inline styles for the container */\n\tstyle?: CSSProperties;\n\t/** Callback fired when the active image index changes */\n\tonIndexChange?: (index: number) => void;\n\t/** Callback fired when all images have finished preloading — only used in \"hover\" mode */\n\tonImagesLoaded?: () => void;\n\t/** Imperative handle ref for start/pause control in \"hover\" mode */\n\tref?: Ref<FlipPreviewerRef>;\n}\n\nexport function FlipPreviewer({\n\tmode = \"position\",\n\timages,\n\twidth,\n\theight,\n\tfit = \"cover\",\n\tdelay,\n\tautoPlay = false,\n\tshowProgress = true,\n\tshowCursor = true,\n\tdebug = false,\n\tclassName,\n\tstyle,\n\tonIndexChange,\n\tonImagesLoaded,\n\tref,\n}: FlipPreviewerProps) {\n\tconst containerRef = useRef<HTMLDivElement>(null);\n\tconst timerRef = useRef<ReturnType<typeof setTimeout> | number | null>(null);\n\n\tconst [activeIndex, setActiveIndex] = useState(0);\n\tconst [debugInfo, setDebugInfo] = useState(\"\");\n\tconst [loadedCount, setLoadedCount] = useState(0);\n\tconst [allLoaded, setAllLoaded] = useState(false);\n\n\tconst activeIndexRef = useRef(0);\n\tconst isPlayingRef = useRef(false);\n\n\t// ── Preload images (hover mode) ──────────────────────────────\n\tuseEffect(() => {\n\t\tif (mode !== \"hover\" || images.length === 0) {\n\t\t\tsetAllLoaded(true);\n\t\t\treturn;\n\t\t}\n\n\t\tlet loaded = 0;\n\t\tsetLoadedCount(0);\n\t\tsetAllLoaded(false);\n\n\t\tconst total = images.length;\n\t\timages.forEach(({ src }) => {\n\t\t\tconst img = new Image();\n\t\t\timg.onload = img.onerror = () => {\n\t\t\t\tloaded++;\n\t\t\t\tsetLoadedCount(loaded);\n\t\t\t\tif (loaded >= total) {\n\t\t\t\t\tsetAllLoaded(true);\n\t\t\t\t\tonImagesLoaded?.();\n\t\t\t\t}\n\t\t\t};\n\t\t\timg.src = src;\n\t\t});\n\t}, [mode, images, onImagesLoaded]);\n\n\t// ── Hover mode: animation ────────────────────────────────────\n\tconst clearTimer = useCallback(() => {\n\t\tif (timerRef.current !== null) {\n\t\t\tif (delay != null) {\n\t\t\t\tclearTimeout(timerRef.current as ReturnType<typeof setTimeout>);\n\t\t\t} else {\n\t\t\t\tcancelAnimationFrame(timerRef.current as number);\n\t\t\t}\n\t\t\ttimerRef.current = null;\n\t\t}\n\t}, [delay]);\n\n\tconst advanceFrame = useCallback(() => {\n\t\tif (!isPlayingRef.current) return;\n\t\tif (images.length <= 1) return;\n\n\t\tconst next =\n\t\t\tactiveIndexRef.current + 1 >= images.length\n\t\t\t\t? 0\n\t\t\t\t: activeIndexRef.current + 1;\n\n\t\tactiveIndexRef.current = next;\n\t\tsetActiveIndex(next);\n\t\tonIndexChange?.(next);\n\n\t\tif (delay != null) {\n\t\t\ttimerRef.current = setTimeout(advanceFrame, delay);\n\t\t} else {\n\t\t\ttimerRef.current = requestAnimationFrame(advanceFrame);\n\t\t}\n\t}, [images.length, delay, onIndexChange]);\n\n\tconst startAnimation = useCallback(() => {\n\t\tif (!allLoaded || images.length <= 1) return;\n\t\tisPlayingRef.current = true;\n\t\tclearTimer();\n\t\tif (delay != null) {\n\t\t\ttimerRef.current = setTimeout(advanceFrame, delay);\n\t\t} else {\n\t\t\ttimerRef.current = requestAnimationFrame(advanceFrame);\n\t\t}\n\t}, [allLoaded, images.length, delay, advanceFrame, clearTimer]);\n\n\tconst stopAnimation = useCallback(() => {\n\t\tisPlayingRef.current = false;\n\t\tclearTimer();\n\t\tactiveIndexRef.current = 0;\n\t\tsetActiveIndex(0);\n\t\tonIndexChange?.(0);\n\t}, [clearTimer, onIndexChange]);\n\n\t// Auto-play on mount if enabled (hover mode)\n\tuseEffect(() => {\n\t\tif (mode === \"hover\" && autoPlay && allLoaded) {\n\t\t\tstartAnimation();\n\t\t}\n\t\treturn () => clearTimer();\n\t}, [mode, autoPlay, allLoaded, startAnimation, clearTimer]);\n\n\t// Expose start/pause via ref (hover mode)\n\tuseImperativeHandle(\n\t\tref,\n\t\t() => ({\n\t\t\tstart: startAnimation,\n\t\t\tpause: stopAnimation,\n\t\t}),\n\t\t[startAnimation, stopAnimation],\n\t);\n\n\tconst handleMouseEnter = useCallback(() => {\n\t\tif (mode === \"hover\" && !autoPlay) {\n\t\t\tstartAnimation();\n\t\t}\n\t}, [mode, autoPlay, startAnimation]);\n\n\tconst handleMouseLeave = useCallback(() => {\n\t\tif (mode === \"hover\" && !autoPlay) {\n\t\t\tstopAnimation();\n\t\t}\n\t}, [mode, autoPlay, stopAnimation]);\n\n\t// ── Position mode: mouse-position-based ──────────────────────\n\tconst handlePointerMove = useCallback(\n\t\t(e: React.PointerEvent<HTMLDivElement>) => {\n\t\t\tif (mode !== \"position\") return;\n\n\t\t\tconst container = containerRef.current;\n\t\t\tif (!container || images.length === 0) return;\n\n\t\t\tconst rect = container.getBoundingClientRect();\n\t\t\tconst x = e.clientX - rect.left;\n\t\t\tlet pos = Math.floor((x / rect.width) * images.length);\n\t\t\tpos = Math.max(0, Math.min(pos, images.length - 1));\n\n\t\t\tif (pos !== activeIndexRef.current) {\n\t\t\t\tactiveIndexRef.current = pos;\n\t\t\t\tsetActiveIndex(pos);\n\t\t\t\tonIndexChange?.(pos);\n\t\t\t}\n\n\t\t\tif (debug) {\n\t\t\t\tconst y = e.clientY - rect.top;\n\t\t\t\tsetDebugInfo(\n\t\t\t\t\t`x:${Math.round(x)}, y:${Math.round(y)}, img:${pos + 1}/${images.length}, w:${Math.round(rect.width)}, h:${Math.round(rect.height)}`,\n\t\t\t\t);\n\t\t\t}\n\t\t},\n\t\t[mode, images.length, debug, onIndexChange],\n\t);\n\n\t// Reset index if images change\n\t// biome-ignore lint/correctness/useExhaustiveDependencies: intentional trigger when images change\n\tuseEffect(() => {\n\t\tsetActiveIndex(0);\n\t\tactiveIndexRef.current = 0;\n\t}, [images]);\n\n\t// ── Render ───────────────────────────────────────────────────\n\tif (images.length === 0) return null;\n\n\tconst activeImage = images[activeIndex];\n\tconst hasLink = !!activeImage.href;\n\n\tconst containerStyle: CSSProperties = {\n\t\tposition: \"relative\",\n\t\twidth: width ?? \"100%\",\n\t\theight: height ?? \"100%\",\n\t\toverflow: \"hidden\",\n\t\tcursor: hasLink\n\t\t\t? \"pointer\"\n\t\t\t: mode === \"position\" && showCursor\n\t\t\t\t? \"ew-resize\"\n\t\t\t\t: \"default\",\n\t\t...style,\n\t};\n\n\tconst imgElement = (\n\t\t<img\n\t\t\tsrc={activeImage.src}\n\t\t\talt={activeImage.alt ?? \"\"}\n\t\t\tclassName=\"cj-flip-previewer__img\"\n\t\t\tstyle={{ objectFit: fit }}\n\t\t\tdraggable={false}\n\t\t/>\n\t);\n\n\tconst content = hasLink ? (\n\t\t<a\n\t\t\thref={activeImage.href}\n\t\t\ttitle={activeImage.title}\n\t\t\ttarget={activeImage.target}\n\t\t\trel={activeImage.rel}\n\t\t\tclassName=\"cj-flip-previewer__link\"\n\t\t>\n\t\t\t{imgElement}\n\t\t</a>\n\t) : (\n\t\timgElement\n\t);\n\n\tconst progressPct =\n\t\timages.length > 0 ? (loadedCount / images.length) * 100 : 0;\n\n\treturn (\n\t\t// biome-ignore lint/a11y/noStaticElementInteractions: container tracks pointer position for image flipping\n\t\t<div\n\t\t\tref={containerRef}\n\t\t\tclassName={`cj-flip-previewer${className ? ` ${className}` : \"\"}`}\n\t\t\tstyle={containerStyle}\n\t\t\tonPointerMove={handlePointerMove}\n\t\t\tonMouseEnter={handleMouseEnter}\n\t\t\tonMouseLeave={handleMouseLeave}\n\t\t>\n\t\t\t{content}\n\n\t\t\t{mode === \"hover\" && showProgress && !allLoaded && (\n\t\t\t\t<div className=\"cj-flip-previewer__progress\">\n\t\t\t\t\t<div\n\t\t\t\t\t\tclassName=\"cj-flip-previewer__progress-bar\"\n\t\t\t\t\t\tstyle={{ width: `${progressPct}%` }}\n\t\t\t\t\t/>\n\t\t\t\t</div>\n\t\t\t)}\n\n\t\t\t{mode === \"position\" && debug && (\n\t\t\t\t<div className=\"cj-flip-previewer__debug\">{debugInfo}</div>\n\t\t\t)}\n\t\t</div>\n\t);\n}\n"],"mappings":"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","names":[]}

package/dist/server.cjs

@@ -0,0 +1,59 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server.ts
+var server_exports = {};
+__export(server_exports, {
+  getImagesFromDirectory: () => getImagesFromDirectory
+});
+module.exports = __toCommonJS(server_exports);
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".gif",
+  ".webp",
+  ".avif",
+  ".svg",
+  ".bmp",
+  ".ico"
+]);
+async function getImagesFromDirectory(fsPath, urlPrefix) {
+  const entries = await (0, import_promises.readdir)(fsPath, { withFileTypes: true });
+  const images = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const ext = (0, import_node_path.extname)(entry.name).toLowerCase();
+    if (!IMAGE_EXTENSIONS.has(ext)) continue;
+    const src = import_node_path.posix.join(
+      urlPrefix.endsWith("/") ? urlPrefix : urlPrefix + "/",
+      entry.name
+    );
+    images.push({ src, alt: entry.name });
+  }
+  images.sort((a, b) => a.src.localeCompare(b.src));
+  return images;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getImagesFromDirectory
+});
+//# sourceMappingURL=server.cjs.map

package/dist/server.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["import { readdir } from \"node:fs/promises\";\nimport { extname, join, posix } from \"node:path\";\nimport type { FlipPreviewerImage } from \"./FlipPreviewer\";\n\nconst IMAGE_EXTENSIONS = new Set([\n  \".jpg\",\n  \".jpeg\",\n  \".png\",\n  \".gif\",\n  \".webp\",\n  \".avif\",\n  \".svg\",\n  \".bmp\",\n  \".ico\",\n]);\n\n/**\n * Reads a directory on the server and returns a sorted array of\n * `FlipPreviewerImage` objects suitable for passing to `<FlipPreviewer>`.\n *\n * @param fsPath - Absolute or relative filesystem path to the image directory\n * @param urlPrefix - URL path prefix for the images (e.g., \"/photos\")\n */\nexport async function getImagesFromDirectory(\n  fsPath: string,\n  urlPrefix: string\n): Promise<FlipPreviewerImage[]> {\n  const entries = await readdir(fsPath, { withFileTypes: true });\n\n  const images: FlipPreviewerImage[] = [];\n\n  for (const entry of entries) {\n    if (!entry.isFile()) continue;\n    const ext = extname(entry.name).toLowerCase();\n    if (!IMAGE_EXTENSIONS.has(ext)) continue;\n\n    const src = posix.join(\n      urlPrefix.endsWith(\"/\") ? urlPrefix : urlPrefix + \"/\",\n      entry.name\n    );\n\n    images.push({ src, alt: entry.name });\n  }\n\n  images.sort((a, b) => a.src.localeCompare(b.src));\n\n  return images;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,sBAAwB;AACxB,uBAAqC;AAGrC,IAAM,mBAAmB,oBAAI,IAAI;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AASD,eAAsB,uBACpB,QACA,WAC+B;AAC/B,QAAM,UAAU,UAAM,yBAAQ,QAAQ,EAAE,eAAe,KAAK,CAAC;AAE7D,QAAM,SAA+B,CAAC;AAEtC,aAAW,SAAS,SAAS;AAC3B,QAAI,CAAC,MAAM,OAAO,EAAG;AACrB,UAAM,UAAM,0BAAQ,MAAM,IAAI,EAAE,YAAY;AAC5C,QAAI,CAAC,iBAAiB,IAAI,GAAG,EAAG;AAEhC,UAAM,MAAM,uBAAM;AAAA,MAChB,UAAU,SAAS,GAAG,IAAI,YAAY,YAAY;AAAA,MAClD,MAAM;AAAA,IACR;AAEA,WAAO,KAAK,EAAE,KAAK,KAAK,MAAM,KAAK,CAAC;AAAA,EACtC;AAEA,SAAO,KAAK,CAAC,GAAG,MAAM,EAAE,IAAI,cAAc,EAAE,GAAG,CAAC;AAEhD,SAAO;AACT;","names":[]}

package/dist/server.d.cts

@@ -0,0 +1,14 @@
+import { FlipPreviewerImage } from './index.cjs';
+import 'react/jsx-runtime';
+import 'react';
+
+/**
+ * Reads a directory on the server and returns a sorted array of
+ * `FlipPreviewerImage` objects suitable for passing to `<FlipPreviewer>`.
+ *
+ * @param fsPath - Absolute or relative filesystem path to the image directory
+ * @param urlPrefix - URL path prefix for the images (e.g., "/photos")
+ */
+declare function getImagesFromDirectory(fsPath: string, urlPrefix: string): Promise<FlipPreviewerImage[]>;
+
+export { getImagesFromDirectory };

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import { FlipPreviewerImage } from './index.js';
+import 'react/jsx-runtime';
+import 'react';
+
+/**
+ * Reads a directory on the server and returns a sorted array of
+ * `FlipPreviewerImage` objects suitable for passing to `<FlipPreviewer>`.
+ *
+ * @param fsPath - Absolute or relative filesystem path to the image directory
+ * @param urlPrefix - URL path prefix for the images (e.g., "/photos")
+ */
+declare function getImagesFromDirectory(fsPath: string, urlPrefix: string): Promise<FlipPreviewerImage[]>;
+
+export { getImagesFromDirectory };

package/dist/server.js

@@ -0,0 +1,34 @@
+// src/server.ts
+import { readdir } from "fs/promises";
+import { extname, posix } from "path";
+var IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".gif",
+  ".webp",
+  ".avif",
+  ".svg",
+  ".bmp",
+  ".ico"
+]);
+async function getImagesFromDirectory(fsPath, urlPrefix) {
+  const entries = await readdir(fsPath, { withFileTypes: true });
+  const images = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const ext = extname(entry.name).toLowerCase();
+    if (!IMAGE_EXTENSIONS.has(ext)) continue;
+    const src = posix.join(
+      urlPrefix.endsWith("/") ? urlPrefix : urlPrefix + "/",
+      entry.name
+    );
+    images.push({ src, alt: entry.name });
+  }
+  images.sort((a, b) => a.src.localeCompare(b.src));
+  return images;
+}
+export {
+  getImagesFromDirectory
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["import { readdir } from \"node:fs/promises\";\nimport { extname, join, posix } from \"node:path\";\nimport type { FlipPreviewerImage } from \"./FlipPreviewer\";\n\nconst IMAGE_EXTENSIONS = new Set([\n  \".jpg\",\n  \".jpeg\",\n  \".png\",\n  \".gif\",\n  \".webp\",\n  \".avif\",\n  \".svg\",\n  \".bmp\",\n  \".ico\",\n]);\n\n/**\n * Reads a directory on the server and returns a sorted array of\n * `FlipPreviewerImage` objects suitable for passing to `<FlipPreviewer>`.\n *\n * @param fsPath - Absolute or relative filesystem path to the image directory\n * @param urlPrefix - URL path prefix for the images (e.g., \"/photos\")\n */\nexport async function getImagesFromDirectory(\n  fsPath: string,\n  urlPrefix: string\n): Promise<FlipPreviewerImage[]> {\n  const entries = await readdir(fsPath, { withFileTypes: true });\n\n  const images: FlipPreviewerImage[] = [];\n\n  for (const entry of entries) {\n    if (!entry.isFile()) continue;\n    const ext = extname(entry.name).toLowerCase();\n    if (!IMAGE_EXTENSIONS.has(ext)) continue;\n\n    const src = posix.join(\n      urlPrefix.endsWith(\"/\") ? urlPrefix : urlPrefix + \"/\",\n      entry.name\n    );\n\n    images.push({ src, alt: entry.name });\n  }\n\n  images.sort((a, b) => a.src.localeCompare(b.src));\n\n  return images;\n}\n"],"mappings":";AAAA,SAAS,eAAe;AACxB,SAAS,SAAe,aAAa;AAGrC,IAAM,mBAAmB,oBAAI,IAAI;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AASD,eAAsB,uBACpB,QACA,WAC+B;AAC/B,QAAM,UAAU,MAAM,QAAQ,QAAQ,EAAE,eAAe,KAAK,CAAC;AAE7D,QAAM,SAA+B,CAAC;AAEtC,aAAW,SAAS,SAAS;AAC3B,QAAI,CAAC,MAAM,OAAO,EAAG;AACrB,UAAM,MAAM,QAAQ,MAAM,IAAI,EAAE,YAAY;AAC5C,QAAI,CAAC,iBAAiB,IAAI,GAAG,EAAG;AAEhC,UAAM,MAAM,MAAM;AAAA,MAChB,UAAU,SAAS,GAAG,IAAI,YAAY,YAAY;AAAA,MAClD,MAAM;AAAA,IACR;AAEA,WAAO,KAAK,EAAE,KAAK,KAAK,MAAM,KAAK,CAAC;AAAA,EACtC;AAEA,SAAO,KAAK,CAAC,GAAG,MAAM,EAAE,IAAI,cAAc,EAAE,GAAG,CAAC;AAEhD,SAAO;AACT;","names":[]}

package/dist/styles.css

@@ -0,0 +1,49 @@
+/* src/styles.css */
+@layer components {
+  .cj-flip-previewer {
+    display: inline-block;
+    user-select: none;
+    touch-action: none;
+  }
+  .cj-flip-previewer__img {
+    display: block;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    pointer-events: none;
+  }
+  .cj-flip-previewer__link {
+    display: block;
+    width: 100%;
+    height: 100%;
+  }
+  .cj-flip-previewer__debug {
+    position: absolute;
+    top: 2px;
+    left: 2px;
+    font-family: monospace;
+    font-size: var(--cj-flip-debug-font-size, 11px);
+    background: var(--cj-flip-debug-bg, rgba(0, 0, 0, 0.6));
+    color: var(--cj-flip-debug-color, #fff);
+    padding: 2px 6px;
+    border-radius: 3px;
+    pointer-events: none;
+    z-index: 10;
+  }
+  .cj-flip-previewer__progress {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: var(--cj-flip-progress-height, 4px);
+    background: var(--cj-flip-progress-bg, rgba(0, 0, 0, 0.3));
+    z-index: 20;
+    overflow: hidden;
+  }
+  .cj-flip-previewer__progress-bar {
+    height: 100%;
+    background: var(--cj-flip-progress-color, #6bc4f7);
+    transition: width var(--cj-flip-progress-speed, 0.2s) ease;
+  }
+}
+/*# sourceMappingURL=styles.css.map */

package/dist/styles.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/styles.css"],"sourcesContent":["@layer components {\n  .cj-flip-previewer {\n    display: inline-block;\n    user-select: none;\n    touch-action: none;\n  }\n\n  .cj-flip-previewer__img {\n    display: block;\n    width: 100%;\n    height: 100%;\n    object-fit: cover;\n    pointer-events: none;\n  }\n\n  .cj-flip-previewer__link {\n    display: block;\n    width: 100%;\n    height: 100%;\n  }\n\n  .cj-flip-previewer__debug {\n    position: absolute;\n    top: 2px;\n    left: 2px;\n    font-family: monospace;\n    font-size: var(--cj-flip-debug-font-size, 11px);\n    background: var(--cj-flip-debug-bg, rgba(0, 0, 0, 0.6));\n    color: var(--cj-flip-debug-color, #fff);\n    padding: 2px 6px;\n    border-radius: 3px;\n    pointer-events: none;\n    z-index: 10;\n  }\n\n  .cj-flip-previewer__progress {\n    position: absolute;\n    top: 0;\n    left: 0;\n    width: 100%;\n    height: var(--cj-flip-progress-height, 4px);\n    background: var(--cj-flip-progress-bg, rgba(0, 0, 0, 0.3));\n    z-index: 20;\n    overflow: hidden;\n  }\n\n  .cj-flip-previewer__progress-bar {\n    height: 100%;\n    background: var(--cj-flip-progress-color, #6bc4f7);\n    transition: width var(--cj-flip-progress-speed, 0.2s) ease;\n  }\n}\n"],"mappings":";AAAA;AACE,GAAC;AACC,aAAS;AACT,iBAAa;AACb,kBAAc;AAChB;AAEA,GAAC;AACC,aAAS;AACT,WAAO;AACP,YAAQ;AACR,gBAAY;AACZ,oBAAgB;AAClB;AAEA,GAAC;AACC,aAAS;AACT,WAAO;AACP,YAAQ;AACV;AAEA,GAAC;AACC,cAAU;AACV,SAAK;AACL,UAAM;AACN,iBAAa;AACb,eAAW,IAAI,yBAAyB,EAAE;AAC1C,gBAAY,IAAI,kBAAkB,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;AAClD,WAAO,IAAI,qBAAqB,EAAE;AAClC,aAAS,IAAI;AACb,mBAAe;AACf,oBAAgB;AAChB,aAAS;AACX;AAEA,GAAC;AACC,cAAU;AACV,SAAK;AACL,UAAM;AACN,WAAO;AACP,YAAQ,IAAI,yBAAyB,EAAE;AACvC,gBAAY,IAAI,qBAAqB,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;AACrD,aAAS;AACT,cAAU;AACZ;AAEA,GAAC;AACC,YAAQ;AACR,gBAAY,IAAI,wBAAwB,EAAE;AAC1C,gBAAY,MAAM,IAAI,wBAAwB,EAAE,MAAM;AACxD;AACF;","names":[]}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@cjboco/cj-image-flip-previewer",
+  "version": "1.0.0",
+  "description": "React components for interactive image previews — flip through images by mouse position (FlipPreviewer) or animate frames on hover like a video previewer (VideoPreviewer).",
+  "author": "Doug Jones",
+  "license": "BSD-3-Clause",
+  "keywords": [
+    "react",
+    "image",
+    "flipbox",
+    "video-previewer",
+    "360",
+    "product-view",
+    "interactive",
+    "mouseover",
+    "hover",
+    "thumbnail",
+    "animation"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      },
+      "require": {
+        "types": "./dist/server.d.cts",
+        "default": "./dist/server.cjs"
+      }
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  }
+}