image-orbit-carousel 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,183 @@
1
- # Temporary Holding Version
1
+ # Image Orbit Carousel
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ An image gallery that moves upright cards around circle, ellipse, infinity or diagonal paths. Configure the orbit, speed and image count; give each image its own link; and optionally turn the other images black and white on hover.
4
+
5
+ Includes responsive sizing, entrance animation, playback controls, keyboard and swipe navigation, reduced-motion support, TypeScript declarations, ESM and CommonJS. React and React DOM are peer dependencies; there are no additional runtime dependencies. No image assets or fonts are required by the library.
6
+
7
+ ## Installation
8
+
9
+ The npm package name is `image-orbit-carousel`. After the first public release:
10
+
11
+ ```sh
12
+ npm install image-orbit-carousel react react-dom
13
+ ```
14
+
15
+ Until publication, build and install the local tarball:
16
+
17
+ ```sh
18
+ npm ci
19
+ npm pack
20
+ # In a consuming React project:
21
+ npm install /path/to/image-orbit-carousel-0.1.0.tgz
22
+ ```
23
+
24
+ The initial version is `0.1.0`. Check the registry again immediately before publishing; a successful local build does not reserve the name.
25
+
26
+ ## Usage
27
+
28
+ ```tsx
29
+ import { ImageOrbitCarousel, type CarouselImage } from 'image-orbit-carousel';
30
+ import 'image-orbit-carousel/styles.css';
31
+
32
+ const images: CarouselImage[] = [
33
+ { src: '/lake.jpg', alt: 'Mountain lake', href: '/gallery/lake' },
34
+ { src: '/forest.jpg', alt: 'Forest', href: 'https://example.com', target: '_blank' },
35
+ { src: '/desert.jpg', alt: 'Desert dunes' },
36
+ ];
37
+
38
+ export default function Gallery() {
39
+ return <ImageOrbitCarousel images={images} path="ellipse"
40
+ radiusX={300} radiusY={140} visibleCount={3}
41
+ direction="counterclockwise" duration={30} style={{ height: 600 }} />;
42
+ }
43
+ ```
44
+
45
+ React 18.2+ and React 19 are supported. The release checks install the tarball in separate React 18.2.0 and 19.0.0 projects and verify imports, server rendering, client mounting, types and a Vite production build. The component also runs in ordinary JavaScript React apps: omit the type import and `: CarouselImage[]` annotation.
46
+
47
+ Next.js App Router: render from a client component and import CSS in your layout or another allowed global CSS entry. Both library bundles retain `"use client"`. Images use native `img`; no Next image domain configuration is needed. Next.js itself is not part of the automated consumer matrix.
48
+
49
+ ## Paths
50
+
51
+ ```jsx
52
+ <ImageOrbitCarousel images={images} path="circle" radius={250} />
53
+ <ImageOrbitCarousel images={images} path="ellipse" radiusX={320} radiusY={130} />
54
+ <ImageOrbitCarousel images={images} path="ellipse" radiusX={130} radiusY={320} />
55
+ <ImageOrbitCarousel images={images} path="infinity" radiusX={300} radiusY={120} />
56
+ <ImageOrbitCarousel images={images} path="diagonal" rotation={-45} />
57
+ ```
58
+
59
+ Cards stay upright. A horizontal ellipse has radiusX greater than radiusY; reverse those values for a vertical ellipse. Rotation turns any path clockwise in degrees. Infinity is a figure eight (`x = radiusX * cos(angle)`, `y = radiusY * sin(2 * angle)`). Its lobes turn in opposite directions; `direction` reverses traversal. Images may overlap at the crossing. Noncircular paths have varying geometric speed.
60
+
61
+ ## API
62
+
63
+ | Prop | Default | Purpose |
64
+ | --- | --- | --- |
65
+ | `images` | required | Array of image objects described below |
66
+ | `path` | `diagonal` | `circle`, `ellipse`, `infinity`, `diagonal` |
67
+ | `direction` | `clockwise` | `clockwise` or `counterclockwise` |
68
+ | `radius` | `400` | Circle radius / default horizontal radius in CSS pixels |
69
+ | `radiusX` | `radius` | Horizontal radius; both circle axes use this |
70
+ | `radiusY` | `radius * 0.6125` | Vertical radius for other paths |
71
+ | `rotation` | diagonal: `45`, others: `0` | Path rotation in degrees |
72
+ | `visibleCount` | `images.length` | First N images, capped at supplied count |
73
+ | `duration` | `24` | Seconds per complete traversal |
74
+ | `imageWidth` | `185` | Card width before responsive scaling |
75
+ | `autoPlay` | `true` | Initial playback; changing this prop updates playback |
76
+ | `animated` | `true` | Automatic entrance fade/slide on mount |
77
+ | `pauseOnHover` | `true` | Pause while hovered |
78
+ | `grayscaleOnHover` | `false` | While an image is hovered, turn the other images black and white |
79
+ | `responsive` | `true` | Scale down path and cards to fit container |
80
+ | `showControls` | `true` | Previous, play/pause, next buttons |
81
+ | `centerContent` | none | Decorative content at center |
82
+ | `className`, `style` | none | Container customization (default height: 700px) |
83
+ | `ariaLabel` | `Image orbit carousel` | Accessible section label |
84
+
85
+ Image objects require `src` and descriptive `alt`; optional fields are `href`, `target` (`_self` or `_blank`), `rel`, `id`, `objectPosition`, and `aspect` (`landscape`, `portrait`, `square`). New-tab links include `noopener noreferrer`. Supply trusted URLs. Landscape is 16:9, portrait is 3:4, square is 1:1.
86
+
87
+ Set each image's destination with `href`; omit it for a non-clickable image. Use `target: '_blank'` to open a new tab, or omit `target` to navigate in the current tab. `direction` controls orbit movement, not link destinations.
88
+
89
+ ```jsx
90
+ const images = [
91
+ { src: '/project-one.jpg', alt: 'Project one', href: '/projects/one' },
92
+ { src: '/project-two.jpg', alt: 'Project two', href: 'https://example.com', target: '_blank' },
93
+ ];
94
+
95
+ <ImageOrbitCarousel images={images} grayscaleOnHover={true} />
96
+ ```
97
+
98
+ The hover effect restores color when the pointer leaves the image and works independently of `pauseOnHover`. It applies on devices that support hover and uses CSS `:has()`.
99
+
100
+ Radii, width and duration must be finite positive numbers. Visible count must be a positive integer; empty arrays are supported. Extra images beyond visibleCount are omitted, rather than cycled into view. Responsive fitting can reduce displayed radii: disable it and provide sufficient container space for exact pixel sizes.
101
+
102
+ Focus the section and use arrow keys, swipe horizontally, or use the buttons. Manual steps move one image spacing immediately. Playback pauses on focus, offscreen, and while the document is hidden. Reduced motion disables autoplay and transitions and responds to preference changes. Keep controls available for autoplay.
103
+
104
+ The optional ref exposes `play()`, `pause()`, `next()`, `previous()`, and `playEntrance()`. Entrance runs automatically; playEntrance remains an idempotent compatibility method. Manual pause persists until play is requested or autoPlay changes. Focus/hover can still suspend a play request.
105
+
106
+ The root exports `ImageOrbitCarousel` and the TypeScript types `CarouselImage`, `ImageOrbitCarouselProps`, `ImageOrbitCarouselHandle`, `OrbitPath` and `OrbitDirection`. ESM imports resolve to `dist/index.js` with `dist/index.d.ts`; CommonJS `require()` resolves to `dist/index.cjs` with `dist/index.d.cts`. The stylesheet export is `image-orbit-carousel/styles.css`.
107
+
108
+ ## Styling and accessibility
109
+
110
+ Import `image-orbit-carousel/styles.css` once. Library rules are scoped to `ioc-*` classes and do not reset the page or add global typography. Override those classes after the import, or use `className` and `style` on the container:
111
+
112
+ ```tsx
113
+ <ImageOrbitCarousel images={images} className="project-orbit" style={{ height: 550 }} />
114
+ ```
115
+
116
+ The container defaults to 100% width and 700px height, with overflow clipped. Responsive sizing only shrinks the orbit and cards. Give the container a positive height and sufficient space if disabling responsive sizing. `centerContent` is decorative and has pointer events disabled; place interactive controls outside it.
117
+
118
+ Use descriptive image `alt` text and an `ariaLabel` that identifies the gallery. Links and controls are keyboard accessible. Unlinked images are not tab stops; use the section's arrow keys or navigation buttons to move them. Keyboard focus suspends autoplay until focus leaves the entire carousel, including its controls. Keep a visible pause control for an automatically moving gallery (`showControls` defaults to `true`). This is an orbit gallery, not a single-slide viewer, and does not announce each animation frame.
119
+
120
+ Use a modern browser with `requestAnimationFrame`, `matchMedia`, CSS individual transforms and `aspect-ratio`. The optional grayscale hover effect also needs CSS `:has()` and a hover-capable pointer; browsers without it keep images in color. Resize/Intersection observers are used when available. Reduced-motion preferences disable autoplay and entrance/filter transitions. Swipe navigation leaves vertical page scrolling available.
121
+
122
+ ## Development and migration
123
+
124
+ Use Node.js 22.12+ and npm for development (the toolchain, rather than the component, requires Node). Install the lockfile's dependencies:
125
+
126
+ ```sh
127
+ npm ci
128
+ npm run dev
129
+ ```
130
+
131
+ Open the URL printed by Vite, usually `http://127.0.0.1:5173`. The demo includes local SVG sample images, live settings, optional image links, the grayscale toggle and a configuration preview. It uses library source directly and is excluded from the published package.
132
+
133
+ Validation:
134
+
135
+ ```sh
136
+ npm run typecheck
137
+ npm test
138
+ npm run build
139
+ npm run build:demo
140
+ npm run test:package
141
+ npm audit
142
+ npm pack --dry-run
143
+ npm pack
144
+ ```
145
+
146
+ No lint script is configured. `prepack` runs type checking, tests and the library build. `test:package` builds the library, checks tarball contents and exports, then installs it into isolated temporary React 18/19 projects. It verifies ESM/CommonJS, SSR, client rendering, keyboard navigation, links, both TypeScript resolution modes and production CSS inclusion. It needs npm registry access and prints the temporary project locations for inspection. CommonJS is retained for existing `require()` consumers and tested alongside ESM. React is externalized in both bundles.
147
+
148
+ The package allowlist includes only JavaScript/declarations, the stylesheet, README, package metadata and a license file when present. The demo, test fixtures, scripts, source files, `.env` files, local caches, archives and `node_modules` are not shipped.
149
+
150
+ Replace the old CSS module import with the package stylesheet. The old component required exactly 14 images and filled the viewport; this component accepts any count and uses a relative container. Fixed branding is replaced by centerContent.
151
+
152
+ ## Manual release
153
+
154
+ A license has not yet been selected or added. Resolve that decision before a public release; add the approved license file and matching SPDX `license` field in `package.json`, then regenerate the tarball. Do not infer permission from the repository being public.
155
+
156
+ After completing the checks above, publish manually from the repository root:
157
+
158
+ ```sh
159
+ npm login
160
+ npm whoami
161
+ npm view image-orbit-carousel version
162
+ # Continue only if the name is unclaimed, or belongs to your account.
163
+ # E404 means no public package was found; authentication/network errors do not.
164
+ npm pack --dry-run
165
+ npm pack
166
+ npm publish ./image-orbit-carousel-0.1.0.tgz
167
+ npm view image-orbit-carousel version
168
+ ```
169
+
170
+ Never publish over a name owned by someone else. If the name is taken, update the package name, README and consumer fixtures and repeat validation. A public scoped name also requires `--access public` on the publish command. If the package already exists under your ownership, preserve its version history and select a new unpublished version instead of reusing `0.1.0`.
171
+
172
+ Verify installation in a separate directory after publication:
173
+
174
+ ```sh
175
+ mkdir carousel-consumer
176
+ cd carousel-consumer
177
+ npm init -y
178
+ npm install image-orbit-carousel@0.1.0 react react-dom
179
+ node --input-type=module -e "import { ImageOrbitCarousel } from 'image-orbit-carousel'; console.log(Boolean(ImageOrbitCarousel));"
180
+ node -e "console.log(require.resolve('image-orbit-carousel/styles.css'));"
181
+ ```
182
+
183
+ Use the example above in that project's React entry point to check the rendered gallery. No publishing automation is configured.
package/dist/index.cjs ADDED
@@ -0,0 +1,276 @@
1
+ "use client";
2
+ "use strict";
3
+ var __defProp = Object.defineProperty;
4
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
5
+ var __getOwnPropNames = Object.getOwnPropertyNames;
6
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
7
+ var __export = (target, all) => {
8
+ for (var name in all)
9
+ __defProp(target, name, { get: all[name], enumerable: true });
10
+ };
11
+ var __copyProps = (to, from, except, desc) => {
12
+ if (from && typeof from === "object" || typeof from === "function") {
13
+ for (let key of __getOwnPropNames(from))
14
+ if (!__hasOwnProp.call(to, key) && key !== except)
15
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
16
+ }
17
+ return to;
18
+ };
19
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
20
+
21
+ // index.ts
22
+ var index_exports = {};
23
+ __export(index_exports, {
24
+ ImageOrbitCarousel: () => ImageOrbitCarousel
25
+ });
26
+ module.exports = __toCommonJS(index_exports);
27
+
28
+ // ImageOrbitCarousel.tsx
29
+ var import_react = require("react");
30
+
31
+ // orbit.ts
32
+ function orbitPoint(angle, path, radiusX, radiusY, rotation) {
33
+ const x = radiusX * Math.cos(angle);
34
+ const y = path === "infinity" ? radiusY * Math.sin(2 * angle) : (path === "circle" ? radiusX : radiusY) * Math.sin(angle);
35
+ const tilt = rotation * Math.PI / 180;
36
+ return { x: x * Math.cos(tilt) - y * Math.sin(tilt), y: x * Math.sin(tilt) + y * Math.cos(tilt) };
37
+ }
38
+ function positive(value, name) {
39
+ if (!Number.isFinite(value) || value <= 0) throw new Error(`${name} must be a finite positive number.`);
40
+ return value;
41
+ }
42
+
43
+ // ImageOrbitCarousel.tsx
44
+ var import_jsx_runtime = require("react/jsx-runtime");
45
+ var ImageOrbitCarousel = (0, import_react.forwardRef)(
46
+ function ImageOrbitCarousel2({
47
+ images,
48
+ path = "diagonal",
49
+ direction = "clockwise",
50
+ radius = 400,
51
+ radiusX = radius,
52
+ radiusY = radius * 0.6125,
53
+ rotation = path === "diagonal" ? 45 : 0,
54
+ visibleCount = images.length,
55
+ duration = 24,
56
+ imageWidth = 185,
57
+ autoPlay = true,
58
+ animated = true,
59
+ pauseOnHover = true,
60
+ grayscaleOnHover = false,
61
+ responsive = true,
62
+ showControls = true,
63
+ centerContent,
64
+ className,
65
+ style,
66
+ ariaLabel = "Image orbit carousel"
67
+ }, ref) {
68
+ positive(radius, "radius");
69
+ positive(radiusX, "radiusX");
70
+ positive(radiusY, "radiusY");
71
+ positive(duration, "duration");
72
+ positive(imageWidth, "imageWidth");
73
+ if (!Number.isFinite(rotation)) throw new Error("rotation must be finite.");
74
+ if (!Number.isInteger(visibleCount) || visibleCount < 0 || images.length > 0 && visibleCount === 0)
75
+ throw new Error("visibleCount must be a positive integer (zero is allowed for an empty gallery).");
76
+ if (!["circle", "ellipse", "infinity", "diagonal"].includes(path)) throw new Error("Invalid orbit path.");
77
+ if (!["clockwise", "counterclockwise"].includes(direction)) throw new Error("Invalid orbit direction.");
78
+ const displayed = images.slice(0, visibleCount);
79
+ const count = displayed.length;
80
+ const root = (0, import_react.useRef)(null);
81
+ const items = (0, import_react.useRef)([]);
82
+ const phase = (0, import_react.useRef)(0);
83
+ const step = (0, import_react.useRef)(() => {
84
+ });
85
+ const pointer = (0, import_react.useRef)(null);
86
+ const suppressClick = (0, import_react.useRef)(false);
87
+ const [playing, setPlaying] = (0, import_react.useState)(autoPlay);
88
+ const [entered, setEntered] = (0, import_react.useState)(false);
89
+ const [hovered, setHovered] = (0, import_react.useState)(false);
90
+ const [focused, setFocused] = (0, import_react.useState)(false);
91
+ const [reduced, setReduced] = (0, import_react.useState)(false);
92
+ const sign = direction === "clockwise" ? 1 : -1;
93
+ (0, import_react.useEffect)(() => {
94
+ setPlaying(autoPlay);
95
+ }, [autoPlay]);
96
+ (0, import_react.useEffect)(() => {
97
+ setEntered(true);
98
+ }, []);
99
+ (0, import_react.useEffect)(() => {
100
+ const query = window.matchMedia("(prefers-reduced-motion: reduce)");
101
+ const update = () => setReduced(query.matches);
102
+ update();
103
+ query.addEventListener("change", update);
104
+ return () => query.removeEventListener("change", update);
105
+ }, []);
106
+ (0, import_react.useImperativeHandle)(ref, () => ({
107
+ playEntrance: () => setEntered(true),
108
+ play: () => setPlaying(true),
109
+ pause: () => setPlaying(false),
110
+ next: () => step.current(sign),
111
+ previous: () => step.current(-sign)
112
+ }), [sign]);
113
+ (0, import_react.useEffect)(() => {
114
+ const element = root.current;
115
+ if (!element || !count) return;
116
+ let scale = 1, visible = true, frame = 0;
117
+ let last = null;
118
+ const render = () => {
119
+ items.current.slice(0, count).forEach((item, index) => {
120
+ if (!item) return;
121
+ const p = orbitPoint(index / count * Math.PI * 2 + phase.current, path, radiusX, radiusY, rotation);
122
+ item.style.transform = `translate(-50%, -50%) translate(${p.x * scale}px, ${p.y * scale}px)`;
123
+ item.style.width = `${imageWidth * scale}px`;
124
+ item.style.zIndex = String(Math.round(p.y + radiusX + radiusY) + 1);
125
+ });
126
+ };
127
+ const resize = () => {
128
+ const tilt = rotation * Math.PI / 180, ry = path === "circle" ? radiusX : radiusY;
129
+ const ex = Math.abs(radiusX * Math.cos(tilt)) + Math.abs(ry * Math.sin(tilt));
130
+ const ey = Math.abs(radiusX * Math.sin(tilt)) + Math.abs(ry * Math.cos(tilt));
131
+ scale = responsive ? Math.min(
132
+ 1,
133
+ element.clientWidth / (2 * ex + imageWidth * 1.2),
134
+ element.clientHeight / (2 * ey + imageWidth * 1.8)
135
+ ) : 1;
136
+ render();
137
+ };
138
+ step.current = (delta) => {
139
+ phase.current = (phase.current + delta * Math.PI * 2 / count) % (Math.PI * 2);
140
+ render();
141
+ };
142
+ const tick = (now) => {
143
+ if (visible && !document.hidden && last !== null) {
144
+ phase.current = (phase.current + sign * Math.min(now - last, 100) / (duration * 1e3) * Math.PI * 2) % (Math.PI * 2);
145
+ render();
146
+ }
147
+ last = now;
148
+ frame = requestAnimationFrame(tick);
149
+ };
150
+ const observer = typeof IntersectionObserver !== "undefined" ? new IntersectionObserver(([entry]) => {
151
+ visible = entry.isIntersecting;
152
+ last = null;
153
+ }) : null;
154
+ observer?.observe(element);
155
+ const resizer = typeof ResizeObserver !== "undefined" ? new ResizeObserver(resize) : null;
156
+ resizer?.observe(element);
157
+ window.addEventListener("resize", resize);
158
+ resize();
159
+ if (playing && !reduced && !(pauseOnHover && hovered) && !focused) frame = requestAnimationFrame(tick);
160
+ return () => {
161
+ cancelAnimationFrame(frame);
162
+ observer?.disconnect();
163
+ resizer?.disconnect();
164
+ window.removeEventListener("resize", resize);
165
+ step.current = () => {
166
+ };
167
+ };
168
+ }, [count, path, radiusX, radiusY, rotation, imageWidth, responsive, playing, reduced, pauseOnHover, hovered, focused, sign, duration]);
169
+ return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
170
+ "section",
171
+ {
172
+ ref: root,
173
+ className: ["ioc", grayscaleOnHover && "ioc-grayscale-on-hover", className].filter(Boolean).join(" "),
174
+ style,
175
+ "aria-label": ariaLabel,
176
+ "aria-roledescription": "carousel",
177
+ tabIndex: 0,
178
+ onPointerEnter: () => setHovered(true),
179
+ onPointerLeave: () => {
180
+ setHovered(false);
181
+ pointer.current = null;
182
+ },
183
+ onFocusCapture: () => setFocused(true),
184
+ onBlurCapture: (e) => {
185
+ if (!e.currentTarget.contains(e.relatedTarget)) setFocused(false);
186
+ },
187
+ onKeyDown: (e) => {
188
+ if (e.target === e.currentTarget && (e.key === "ArrowRight" || e.key === "ArrowLeft")) {
189
+ e.preventDefault();
190
+ step.current(e.key === "ArrowRight" ? sign : -sign);
191
+ }
192
+ },
193
+ onPointerDown: (e) => {
194
+ if (e.button !== 0 || e.target.closest("button")) return;
195
+ pointer.current = { x: e.clientX, y: e.clientY };
196
+ suppressClick.current = false;
197
+ },
198
+ onPointerMove: (e) => {
199
+ const p = pointer.current;
200
+ if (p && Math.abs(e.clientX - p.x) > 40 && Math.abs(e.clientX - p.x) > Math.abs(e.clientY - p.y)) suppressClick.current = true;
201
+ },
202
+ onPointerUp: (e) => {
203
+ const p = pointer.current;
204
+ pointer.current = null;
205
+ if (!p) return;
206
+ const dx = e.clientX - p.x;
207
+ if (Math.abs(dx) > 40 && Math.abs(dx) > Math.abs(e.clientY - p.y)) {
208
+ suppressClick.current = true;
209
+ step.current(dx < 0 ? sign : -sign);
210
+ }
211
+ },
212
+ onPointerCancel: () => {
213
+ pointer.current = null;
214
+ },
215
+ onClickCapture: (e) => {
216
+ if (suppressClick.current) {
217
+ e.preventDefault();
218
+ e.stopPropagation();
219
+ suppressClick.current = false;
220
+ }
221
+ },
222
+ children: [
223
+ /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "ioc-orbit", role: "list", children: displayed.map((image, index) => {
224
+ const p = orbitPoint(index / count * Math.PI * 2, path, radiusX, radiusY, rotation);
225
+ const picture = /* @__PURE__ */ (0, import_jsx_runtime.jsx)("img", { src: image.src, alt: image.alt, draggable: false, className: "ioc-image", style: { objectPosition: image.objectPosition } });
226
+ return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
227
+ "div",
228
+ {
229
+ ref: (node) => {
230
+ items.current[index] = node;
231
+ },
232
+ role: "listitem",
233
+ className: "ioc-item",
234
+ style: {
235
+ width: imageWidth,
236
+ transform: `translate(-50%, -50%) translate(${p.x}px, ${p.y}px)`,
237
+ aspectRatio: image.aspect === "portrait" ? "3 / 4" : image.aspect === "square" ? "1" : "16 / 9"
238
+ },
239
+ children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: `ioc-frame${animated && !reduced ? " ioc-entrance" : ""}`, "data-entered": entered, children: image.href ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
240
+ "a",
241
+ {
242
+ className: "ioc-link",
243
+ href: image.href,
244
+ target: image.target,
245
+ rel: image.target === "_blank" ? `${image.rel ?? ""} noopener noreferrer`.trim() : image.rel,
246
+ children: picture
247
+ }
248
+ ) : picture })
249
+ },
250
+ image.id ?? `${image.src}-${index}`
251
+ );
252
+ }) }),
253
+ centerContent != null && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "ioc-center", children: centerContent }),
254
+ showControls && count > 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "ioc-controls", children: [
255
+ /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", onClick: () => step.current(-sign), "aria-label": "Previous position", children: "Previous" }),
256
+ /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
257
+ "button",
258
+ {
259
+ type: "button",
260
+ onClick: () => setPlaying(!playing),
261
+ disabled: reduced,
262
+ "aria-label": playing && !reduced ? "Pause orbit" : "Play orbit",
263
+ children: playing && !reduced ? "Pause" : "Play"
264
+ }
265
+ ),
266
+ /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", onClick: () => step.current(sign), "aria-label": "Next position", children: "Next" })
267
+ ] })
268
+ ]
269
+ }
270
+ );
271
+ }
272
+ );
273
+ // Annotate the CommonJS export names for ESM import in node:
274
+ 0 && (module.exports = {
275
+ ImageOrbitCarousel
276
+ });
@@ -0,0 +1,48 @@
1
+ import * as react from 'react';
2
+ import { ReactNode, CSSProperties } from 'react';
3
+
4
+ type OrbitPath = 'circle' | 'ellipse' | 'infinity' | 'diagonal';
5
+ type OrbitDirection = 'clockwise' | 'counterclockwise';
6
+
7
+ type CarouselImage = {
8
+ id?: string;
9
+ src: string;
10
+ alt: string;
11
+ href?: string;
12
+ target?: '_self' | '_blank';
13
+ rel?: string;
14
+ objectPosition?: string;
15
+ aspect?: 'landscape' | 'portrait' | 'square';
16
+ };
17
+ type ImageOrbitCarouselProps = {
18
+ images: readonly CarouselImage[];
19
+ path?: OrbitPath;
20
+ direction?: OrbitDirection;
21
+ radius?: number;
22
+ radiusX?: number;
23
+ radiusY?: number;
24
+ rotation?: number;
25
+ visibleCount?: number;
26
+ duration?: number;
27
+ imageWidth?: number;
28
+ autoPlay?: boolean;
29
+ animated?: boolean;
30
+ pauseOnHover?: boolean;
31
+ grayscaleOnHover?: boolean;
32
+ responsive?: boolean;
33
+ showControls?: boolean;
34
+ centerContent?: ReactNode;
35
+ className?: string;
36
+ style?: CSSProperties;
37
+ ariaLabel?: string;
38
+ };
39
+ type ImageOrbitCarouselHandle = {
40
+ playEntrance: () => void;
41
+ play: () => void;
42
+ pause: () => void;
43
+ next: () => void;
44
+ previous: () => void;
45
+ };
46
+ declare const ImageOrbitCarousel: react.ForwardRefExoticComponent<ImageOrbitCarouselProps & react.RefAttributes<ImageOrbitCarouselHandle>>;
47
+
48
+ export { type CarouselImage, ImageOrbitCarousel, type ImageOrbitCarouselHandle, type ImageOrbitCarouselProps, type OrbitDirection, type OrbitPath };
@@ -0,0 +1,48 @@
1
+ import * as react from 'react';
2
+ import { ReactNode, CSSProperties } from 'react';
3
+
4
+ type OrbitPath = 'circle' | 'ellipse' | 'infinity' | 'diagonal';
5
+ type OrbitDirection = 'clockwise' | 'counterclockwise';
6
+
7
+ type CarouselImage = {
8
+ id?: string;
9
+ src: string;
10
+ alt: string;
11
+ href?: string;
12
+ target?: '_self' | '_blank';
13
+ rel?: string;
14
+ objectPosition?: string;
15
+ aspect?: 'landscape' | 'portrait' | 'square';
16
+ };
17
+ type ImageOrbitCarouselProps = {
18
+ images: readonly CarouselImage[];
19
+ path?: OrbitPath;
20
+ direction?: OrbitDirection;
21
+ radius?: number;
22
+ radiusX?: number;
23
+ radiusY?: number;
24
+ rotation?: number;
25
+ visibleCount?: number;
26
+ duration?: number;
27
+ imageWidth?: number;
28
+ autoPlay?: boolean;
29
+ animated?: boolean;
30
+ pauseOnHover?: boolean;
31
+ grayscaleOnHover?: boolean;
32
+ responsive?: boolean;
33
+ showControls?: boolean;
34
+ centerContent?: ReactNode;
35
+ className?: string;
36
+ style?: CSSProperties;
37
+ ariaLabel?: string;
38
+ };
39
+ type ImageOrbitCarouselHandle = {
40
+ playEntrance: () => void;
41
+ play: () => void;
42
+ pause: () => void;
43
+ next: () => void;
44
+ previous: () => void;
45
+ };
46
+ declare const ImageOrbitCarousel: react.ForwardRefExoticComponent<ImageOrbitCarouselProps & react.RefAttributes<ImageOrbitCarouselHandle>>;
47
+
48
+ export { type CarouselImage, ImageOrbitCarousel, type ImageOrbitCarouselHandle, type ImageOrbitCarouselProps, type OrbitDirection, type OrbitPath };
package/dist/index.js ADDED
@@ -0,0 +1,250 @@
1
+ "use client";
2
+
3
+ // ImageOrbitCarousel.tsx
4
+ import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from "react";
5
+
6
+ // orbit.ts
7
+ function orbitPoint(angle, path, radiusX, radiusY, rotation) {
8
+ const x = radiusX * Math.cos(angle);
9
+ const y = path === "infinity" ? radiusY * Math.sin(2 * angle) : (path === "circle" ? radiusX : radiusY) * Math.sin(angle);
10
+ const tilt = rotation * Math.PI / 180;
11
+ return { x: x * Math.cos(tilt) - y * Math.sin(tilt), y: x * Math.sin(tilt) + y * Math.cos(tilt) };
12
+ }
13
+ function positive(value, name) {
14
+ if (!Number.isFinite(value) || value <= 0) throw new Error(`${name} must be a finite positive number.`);
15
+ return value;
16
+ }
17
+
18
+ // ImageOrbitCarousel.tsx
19
+ import { jsx, jsxs } from "react/jsx-runtime";
20
+ var ImageOrbitCarousel = forwardRef(
21
+ function ImageOrbitCarousel2({
22
+ images,
23
+ path = "diagonal",
24
+ direction = "clockwise",
25
+ radius = 400,
26
+ radiusX = radius,
27
+ radiusY = radius * 0.6125,
28
+ rotation = path === "diagonal" ? 45 : 0,
29
+ visibleCount = images.length,
30
+ duration = 24,
31
+ imageWidth = 185,
32
+ autoPlay = true,
33
+ animated = true,
34
+ pauseOnHover = true,
35
+ grayscaleOnHover = false,
36
+ responsive = true,
37
+ showControls = true,
38
+ centerContent,
39
+ className,
40
+ style,
41
+ ariaLabel = "Image orbit carousel"
42
+ }, ref) {
43
+ positive(radius, "radius");
44
+ positive(radiusX, "radiusX");
45
+ positive(radiusY, "radiusY");
46
+ positive(duration, "duration");
47
+ positive(imageWidth, "imageWidth");
48
+ if (!Number.isFinite(rotation)) throw new Error("rotation must be finite.");
49
+ if (!Number.isInteger(visibleCount) || visibleCount < 0 || images.length > 0 && visibleCount === 0)
50
+ throw new Error("visibleCount must be a positive integer (zero is allowed for an empty gallery).");
51
+ if (!["circle", "ellipse", "infinity", "diagonal"].includes(path)) throw new Error("Invalid orbit path.");
52
+ if (!["clockwise", "counterclockwise"].includes(direction)) throw new Error("Invalid orbit direction.");
53
+ const displayed = images.slice(0, visibleCount);
54
+ const count = displayed.length;
55
+ const root = useRef(null);
56
+ const items = useRef([]);
57
+ const phase = useRef(0);
58
+ const step = useRef(() => {
59
+ });
60
+ const pointer = useRef(null);
61
+ const suppressClick = useRef(false);
62
+ const [playing, setPlaying] = useState(autoPlay);
63
+ const [entered, setEntered] = useState(false);
64
+ const [hovered, setHovered] = useState(false);
65
+ const [focused, setFocused] = useState(false);
66
+ const [reduced, setReduced] = useState(false);
67
+ const sign = direction === "clockwise" ? 1 : -1;
68
+ useEffect(() => {
69
+ setPlaying(autoPlay);
70
+ }, [autoPlay]);
71
+ useEffect(() => {
72
+ setEntered(true);
73
+ }, []);
74
+ useEffect(() => {
75
+ const query = window.matchMedia("(prefers-reduced-motion: reduce)");
76
+ const update = () => setReduced(query.matches);
77
+ update();
78
+ query.addEventListener("change", update);
79
+ return () => query.removeEventListener("change", update);
80
+ }, []);
81
+ useImperativeHandle(ref, () => ({
82
+ playEntrance: () => setEntered(true),
83
+ play: () => setPlaying(true),
84
+ pause: () => setPlaying(false),
85
+ next: () => step.current(sign),
86
+ previous: () => step.current(-sign)
87
+ }), [sign]);
88
+ useEffect(() => {
89
+ const element = root.current;
90
+ if (!element || !count) return;
91
+ let scale = 1, visible = true, frame = 0;
92
+ let last = null;
93
+ const render = () => {
94
+ items.current.slice(0, count).forEach((item, index) => {
95
+ if (!item) return;
96
+ const p = orbitPoint(index / count * Math.PI * 2 + phase.current, path, radiusX, radiusY, rotation);
97
+ item.style.transform = `translate(-50%, -50%) translate(${p.x * scale}px, ${p.y * scale}px)`;
98
+ item.style.width = `${imageWidth * scale}px`;
99
+ item.style.zIndex = String(Math.round(p.y + radiusX + radiusY) + 1);
100
+ });
101
+ };
102
+ const resize = () => {
103
+ const tilt = rotation * Math.PI / 180, ry = path === "circle" ? radiusX : radiusY;
104
+ const ex = Math.abs(radiusX * Math.cos(tilt)) + Math.abs(ry * Math.sin(tilt));
105
+ const ey = Math.abs(radiusX * Math.sin(tilt)) + Math.abs(ry * Math.cos(tilt));
106
+ scale = responsive ? Math.min(
107
+ 1,
108
+ element.clientWidth / (2 * ex + imageWidth * 1.2),
109
+ element.clientHeight / (2 * ey + imageWidth * 1.8)
110
+ ) : 1;
111
+ render();
112
+ };
113
+ step.current = (delta) => {
114
+ phase.current = (phase.current + delta * Math.PI * 2 / count) % (Math.PI * 2);
115
+ render();
116
+ };
117
+ const tick = (now) => {
118
+ if (visible && !document.hidden && last !== null) {
119
+ phase.current = (phase.current + sign * Math.min(now - last, 100) / (duration * 1e3) * Math.PI * 2) % (Math.PI * 2);
120
+ render();
121
+ }
122
+ last = now;
123
+ frame = requestAnimationFrame(tick);
124
+ };
125
+ const observer = typeof IntersectionObserver !== "undefined" ? new IntersectionObserver(([entry]) => {
126
+ visible = entry.isIntersecting;
127
+ last = null;
128
+ }) : null;
129
+ observer?.observe(element);
130
+ const resizer = typeof ResizeObserver !== "undefined" ? new ResizeObserver(resize) : null;
131
+ resizer?.observe(element);
132
+ window.addEventListener("resize", resize);
133
+ resize();
134
+ if (playing && !reduced && !(pauseOnHover && hovered) && !focused) frame = requestAnimationFrame(tick);
135
+ return () => {
136
+ cancelAnimationFrame(frame);
137
+ observer?.disconnect();
138
+ resizer?.disconnect();
139
+ window.removeEventListener("resize", resize);
140
+ step.current = () => {
141
+ };
142
+ };
143
+ }, [count, path, radiusX, radiusY, rotation, imageWidth, responsive, playing, reduced, pauseOnHover, hovered, focused, sign, duration]);
144
+ return /* @__PURE__ */ jsxs(
145
+ "section",
146
+ {
147
+ ref: root,
148
+ className: ["ioc", grayscaleOnHover && "ioc-grayscale-on-hover", className].filter(Boolean).join(" "),
149
+ style,
150
+ "aria-label": ariaLabel,
151
+ "aria-roledescription": "carousel",
152
+ tabIndex: 0,
153
+ onPointerEnter: () => setHovered(true),
154
+ onPointerLeave: () => {
155
+ setHovered(false);
156
+ pointer.current = null;
157
+ },
158
+ onFocusCapture: () => setFocused(true),
159
+ onBlurCapture: (e) => {
160
+ if (!e.currentTarget.contains(e.relatedTarget)) setFocused(false);
161
+ },
162
+ onKeyDown: (e) => {
163
+ if (e.target === e.currentTarget && (e.key === "ArrowRight" || e.key === "ArrowLeft")) {
164
+ e.preventDefault();
165
+ step.current(e.key === "ArrowRight" ? sign : -sign);
166
+ }
167
+ },
168
+ onPointerDown: (e) => {
169
+ if (e.button !== 0 || e.target.closest("button")) return;
170
+ pointer.current = { x: e.clientX, y: e.clientY };
171
+ suppressClick.current = false;
172
+ },
173
+ onPointerMove: (e) => {
174
+ const p = pointer.current;
175
+ if (p && Math.abs(e.clientX - p.x) > 40 && Math.abs(e.clientX - p.x) > Math.abs(e.clientY - p.y)) suppressClick.current = true;
176
+ },
177
+ onPointerUp: (e) => {
178
+ const p = pointer.current;
179
+ pointer.current = null;
180
+ if (!p) return;
181
+ const dx = e.clientX - p.x;
182
+ if (Math.abs(dx) > 40 && Math.abs(dx) > Math.abs(e.clientY - p.y)) {
183
+ suppressClick.current = true;
184
+ step.current(dx < 0 ? sign : -sign);
185
+ }
186
+ },
187
+ onPointerCancel: () => {
188
+ pointer.current = null;
189
+ },
190
+ onClickCapture: (e) => {
191
+ if (suppressClick.current) {
192
+ e.preventDefault();
193
+ e.stopPropagation();
194
+ suppressClick.current = false;
195
+ }
196
+ },
197
+ children: [
198
+ /* @__PURE__ */ jsx("div", { className: "ioc-orbit", role: "list", children: displayed.map((image, index) => {
199
+ const p = orbitPoint(index / count * Math.PI * 2, path, radiusX, radiusY, rotation);
200
+ const picture = /* @__PURE__ */ jsx("img", { src: image.src, alt: image.alt, draggable: false, className: "ioc-image", style: { objectPosition: image.objectPosition } });
201
+ return /* @__PURE__ */ jsx(
202
+ "div",
203
+ {
204
+ ref: (node) => {
205
+ items.current[index] = node;
206
+ },
207
+ role: "listitem",
208
+ className: "ioc-item",
209
+ style: {
210
+ width: imageWidth,
211
+ transform: `translate(-50%, -50%) translate(${p.x}px, ${p.y}px)`,
212
+ aspectRatio: image.aspect === "portrait" ? "3 / 4" : image.aspect === "square" ? "1" : "16 / 9"
213
+ },
214
+ children: /* @__PURE__ */ jsx("div", { className: `ioc-frame${animated && !reduced ? " ioc-entrance" : ""}`, "data-entered": entered, children: image.href ? /* @__PURE__ */ jsx(
215
+ "a",
216
+ {
217
+ className: "ioc-link",
218
+ href: image.href,
219
+ target: image.target,
220
+ rel: image.target === "_blank" ? `${image.rel ?? ""} noopener noreferrer`.trim() : image.rel,
221
+ children: picture
222
+ }
223
+ ) : picture })
224
+ },
225
+ image.id ?? `${image.src}-${index}`
226
+ );
227
+ }) }),
228
+ centerContent != null && /* @__PURE__ */ jsx("div", { className: "ioc-center", children: centerContent }),
229
+ showControls && count > 0 && /* @__PURE__ */ jsxs("div", { className: "ioc-controls", children: [
230
+ /* @__PURE__ */ jsx("button", { type: "button", onClick: () => step.current(-sign), "aria-label": "Previous position", children: "Previous" }),
231
+ /* @__PURE__ */ jsx(
232
+ "button",
233
+ {
234
+ type: "button",
235
+ onClick: () => setPlaying(!playing),
236
+ disabled: reduced,
237
+ "aria-label": playing && !reduced ? "Pause orbit" : "Play orbit",
238
+ children: playing && !reduced ? "Pause" : "Play"
239
+ }
240
+ ),
241
+ /* @__PURE__ */ jsx("button", { type: "button", onClick: () => step.current(sign), "aria-label": "Next position", children: "Next" })
242
+ ] })
243
+ ]
244
+ }
245
+ );
246
+ }
247
+ );
248
+ export {
249
+ ImageOrbitCarousel
250
+ };
@@ -0,0 +1,19 @@
1
+ .ioc { position: relative; width: 100%; height: 700px; overflow: hidden; touch-action: pan-y; isolation: isolate; }
2
+ .ioc-orbit { position: absolute; inset: 0; }
3
+ .ioc-item { position: absolute; top: 50%; left: 50%; }
4
+ .ioc-frame { width: 100%; height: 100%; transition: scale .25s ease; }
5
+ .ioc-item:hover, .ioc-item:focus-within { z-index: 2147483647 !important; }
6
+ .ioc-frame:hover, .ioc-frame:focus-within { scale: 1.12; }
7
+ .ioc-link { display: block; width: 100%; height: 100%; }
8
+ .ioc-image { display: block; width: 100%; height: 100%; object-fit: cover; border-radius: 4px; user-select: none; }
9
+ .ioc-grayscale-on-hover .ioc-image { transition: filter .25s ease; }
10
+ @media (hover: hover) {
11
+ .ioc-grayscale-on-hover .ioc-orbit:has(.ioc-item:hover) .ioc-item:not(:hover) .ioc-image { filter: grayscale(1); }
12
+ }
13
+ .ioc-entrance { opacity: 0; translate: 0 24px; transition: opacity .6s ease, translate .6s ease, scale .25s ease; }
14
+ .ioc-entrance[data-entered="true"] { opacity: 1; translate: 0 0; }
15
+ .ioc-center { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); pointer-events: none; }
16
+ .ioc-controls { position: absolute; bottom: 12px; left: 50%; transform: translateX(-50%); display: flex; gap: 8px; z-index: 2147483647; }
17
+ .ioc-controls button { padding: 8px 12px; cursor: pointer; }
18
+ .ioc :focus-visible, .ioc:focus-visible { outline: 2px solid currentColor; outline-offset: 4px; }
19
+ @media (prefers-reduced-motion: reduce) { .ioc-frame, .ioc-grayscale-on-hover .ioc-image { transition: none; } .ioc-entrance { opacity: 1; translate: none; } }
package/package.json CHANGED
@@ -1,6 +1,70 @@
1
1
  {
2
2
  "name": "image-orbit-carousel",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Responsive React image carousel with configurable orbit paths, image links and optional grayscale hover",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/plavovic/orbital-image-carousel.git"
8
+ },
9
+ "homepage": "https://github.com/plavovic/orbital-image-carousel#readme",
10
+ "bugs": {
11
+ "url": "https://github.com/plavovic/orbital-image-carousel/issues"
12
+ },
13
+ "keywords": ["react", "carousel", "image-gallery", "orbit", "animation", "typescript"],
14
+ "type": "module",
15
+ "main": "./dist/index.cjs",
16
+ "module": "./dist/index.js",
17
+ "types": "./dist/index.d.ts",
18
+ "exports": {
19
+ ".": {
20
+ "import": {
21
+ "types": "./dist/index.d.ts",
22
+ "default": "./dist/index.js"
23
+ },
24
+ "require": {
25
+ "types": "./dist/index.d.cts",
26
+ "default": "./dist/index.cjs"
27
+ }
28
+ },
29
+ "./styles.css": "./dist/styles.css"
30
+ },
31
+ "files": [
32
+ "dist/index.js",
33
+ "dist/index.cjs",
34
+ "dist/index.d.ts",
35
+ "dist/index.d.cts",
36
+ "dist/styles.css",
37
+ "README.md",
38
+ "LICENSE"
39
+ ],
40
+ "sideEffects": [
41
+ "**/*.css"
42
+ ],
43
+ "scripts": {
44
+ "dev": "vite demo --host 127.0.0.1",
45
+ "build:demo": "vite build demo --outDir ../demo-dist",
46
+ "build": "tsup && node scripts/copy-css.mjs",
47
+ "typecheck": "tsc --noEmit",
48
+ "test": "vitest run",
49
+ "pretest:package": "npm run build",
50
+ "test:package": "node scripts/check-package.mjs",
51
+ "prepack": "npm run typecheck && npm test && npm run build"
52
+ },
53
+ "peerDependencies": {
54
+ "react": "^18.2.0 || ^19.0.0",
55
+ "react-dom": "^18.2.0 || ^19.0.0"
56
+ },
57
+ "overrides": { "esbuild": "$esbuild" },
58
+ "devDependencies": {
59
+ "@types/react": "^19.0.0",
60
+ "@types/react-dom": "^19.0.0",
61
+ "esbuild": "0.28.1",
62
+ "jsdom": "^26.0.0",
63
+ "react": "^19.0.0",
64
+ "react-dom": "^19.0.0",
65
+ "tsup": "^8.5.0",
66
+ "typescript": "^5.8.0",
67
+ "vitest": "^5.0.4",
68
+ "vite": "^8.0.0"
69
+ }
70
+ }