@juniorxsound/react-three-components 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juniorxsound
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+# @juniorxsound/react-three-components
+
+[![npm version](https://img.shields.io/npm/v/@juniorxsound/react-three-components.svg)](https://www.npmjs.com/package/@juniorxsound/react-three-components)
+[![CI](https://github.com/juniorxsound/react-three-components/actions/workflows/ci.yml/badge.svg)](https://github.com/juniorxsound/react-three-components/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@juniorxsound/react-three-components.svg)](https://github.com/juniorxsound/react-three-components/blob/main/LICENSE)
+
+3D carousel components for React Three Fiber with gesture support.
+
+## Installation
+
+```bash
+npm install @juniorxsound/react-three-components
+```
+
+### Peer Dependencies
+
+This library requires the following peer dependencies:
+
+```bash
+npm install react react-dom three @react-three/fiber @react-spring/web @use-gesture/react
+```
+
+## Components
+
+### CircularCarousel
+
+A 3D carousel that arranges items in a circle and rotates around an axis.
+
+```tsx
+import { Canvas } from "@react-three/fiber";
+import { CircularCarousel, useCarouselContext } from "@juniorxsound/react-three-components";
+
+function Item({ index }: { index: number }) {
+  const { activeIndex } = useCarouselContext();
+  const isActive = index === activeIndex;
+  
+  return (
+    <mesh>
+      <boxGeometry args={[1, 1, 1]} />
+      <meshStandardMaterial color={isActive ? "hotpink" : "gray"} />
+    </mesh>
+  );
+}
+
+function App() {
+  return (
+    <Canvas>
+      <CircularCarousel radius={3} onIndexChange={(i) => console.log(i)}>
+        <Item index={0} />
+        <Item index={1} />
+        <Item index={2} />
+        <Item index={3} />
+      </CircularCarousel>
+    </Canvas>
+  );
+}
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | required | Carousel items |
+| `radius` | `number` | `3` | Distance from center to items |
+| `axis` | `"x" \| "y" \| "z"` | `"y"` | Rotation axis |
+| `index` | `number` | - | Controlled active index |
+| `defaultIndex` | `number` | `0` | Initial index (uncontrolled) |
+| `onIndexChange` | `(index: number) => void` | - | Called when index changes |
+| `dragEnabled` | `boolean` | `true` | Enable drag gestures |
+| `dragSensitivity` | `number` | auto | Drag sensitivity |
+| `dragAxis` | `"x" \| "y"` | `"x"` | Drag gesture axis |
+| `dragConfig` | `DragConfig` | - | Additional drag options |
+
+#### Ref Methods
+
+```tsx
+const ref = useRef<CircularCarouselRef>(null);
+
+ref.current.next();      // Go to next item
+ref.current.prev();      // Go to previous item
+ref.current.goTo(2);     // Go to specific index
+```
+
+#### With Navigation Triggers
+
+```tsx
+<CircularCarousel>
+  <Item index={0} />
+  <Item index={1} />
+  <Item index={2} />
+  
+  <CircularCarousel.PrevTrigger position={[-2, 0, 0]}>
+    <mesh><boxGeometry /><meshBasicMaterial color="blue" /></mesh>
+  </CircularCarousel.PrevTrigger>
+  
+  <CircularCarousel.NextTrigger position={[2, 0, 0]}>
+    <mesh><boxGeometry /><meshBasicMaterial color="red" /></mesh>
+  </CircularCarousel.NextTrigger>
+</CircularCarousel>
+```
+
+---
+
+### LinearCarousel
+
+A carousel that slides items linearly (horizontally or vertically).
+
+```tsx
+import { Canvas } from "@react-three/fiber";
+import { LinearCarousel, useLinearCarouselContext } from "@juniorxsound/react-three-components";
+
+function Item({ index }: { index: number }) {
+  const { activeIndex } = useLinearCarouselContext();
+  const isActive = index === activeIndex;
+  
+  return (
+    <mesh scale={isActive ? 1.2 : 1}>
+      <planeGeometry args={[2, 1.5]} />
+      <meshBasicMaterial color={isActive ? "hotpink" : "gray"} />
+    </mesh>
+  );
+}
+
+function App() {
+  return (
+    <Canvas>
+      <LinearCarousel gap={0.5} direction="horizontal">
+        <Item index={0} />
+        <Item index={1} />
+        <Item index={2} />
+        <Item index={3} />
+      </LinearCarousel>
+    </Canvas>
+  );
+}
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | required | Carousel items |
+| `gap` | `number` | `0.2` | Space between items |
+| `direction` | `"horizontal" \| "vertical"` | `"horizontal"` | Slide direction |
+| `index` | `number` | - | Controlled active index |
+| `defaultIndex` | `number` | `0` | Initial index (uncontrolled) |
+| `onIndexChange` | `(index: number) => void` | - | Called when index changes |
+| `dragEnabled` | `boolean` | `true` | Enable drag gestures |
+| `dragSensitivity` | `number` | `150` | Drag sensitivity |
+| `dragAxis` | `"x" \| "y"` | auto | Drag axis (derived from direction) |
+| `dragConfig` | `DragConfig` | - | Additional drag options |
+
+#### Ref Methods
+
+```tsx
+const ref = useRef<LinearCarouselRef>(null);
+
+ref.current.next();      // Go to next item (bounded)
+ref.current.prev();      // Go to previous item (bounded)
+ref.current.goTo(2);     // Go to specific index
+```
+
+> Note: LinearCarousel is bounded (doesn't wrap around), unlike CircularCarousel which loops infinitely.
+
+#### With Navigation Triggers
+
+```tsx
+<LinearCarousel>
+  <Item index={0} />
+  <Item index={1} />
+  <Item index={2} />
+  
+  <LinearCarousel.PrevTrigger position={[-3, 0, 0]}>
+    <PrevButton />
+  </LinearCarousel.PrevTrigger>
+  
+  <LinearCarousel.NextTrigger position={[3, 0, 0]}>
+    <NextButton />
+  </LinearCarousel.NextTrigger>
+</LinearCarousel>
+```
+
+---
+
+## Context Hooks
+
+Access carousel state from any child component:
+
+```tsx
+// For CircularCarousel
+import { useCarouselContext } from "@juniorxsound/react-three-components";
+
+const { activeIndex, count, next, prev, goTo } = useCarouselContext();
+
+// For LinearCarousel
+import { useLinearCarouselContext } from "@juniorxsound/react-three-components";
+
+const { activeIndex, count, next, prev, goTo } = useLinearCarouselContext();
+```
+
+## DragConfig
+
+Fine-tune drag behavior:
+
+```tsx
+<CircularCarousel
+  dragConfig={{
+    axis: "x",                    // Constrain to axis
+    threshold: 10,                // Pixels before drag starts
+    rubberband: 0.2,              // Elastic effect at bounds
+    touchAction: "pan-y",         // CSS touch-action
+    pointer: { touch: true },     // Pointer options
+  }}
+>
+```
+
+## Contributing
+
+### Development
+
+```bash
+nvm use              # Switch to Node 24 (uses .nvmrc)
+npm install          # Install dependencies
+npm run dev          # Start Storybook dev server
+npm run test         # Run tests in watch mode
+npm run lint         # Run ESLint
+npm run build        # Build the library
+```
+
+### Releasing
+
+This package uses [npm trusted publishers](https://docs.npmjs.com/trusted-publishers) for secure, token-free publishing.
+
+```bash
+npm run release:patch   # 0.1.0 → 0.1.1
+npm run release:minor   # 0.1.0 → 0.2.0
+npm run release:major   # 0.1.0 → 1.0.0
+```
+
+Then create a GitHub Release from the tag - this triggers automatic npm publish with provenance.
+
+## License
+
+MIT

package/dist/components/CircularCarousel/CircularCarousel.d.ts

@@ -0,0 +1,9 @@
+import { type ForwardRefExoticComponent, type RefAttributes } from "react";
+import { CircularCarouselNextTrigger, CircularCarouselPrevTrigger } from "./CircularCarouselTriggers";
+import type { CircularCarouselProps, CircularCarouselRef } from "./types";
+type CircularCarouselComponent = ForwardRefExoticComponent<CircularCarouselProps & RefAttributes<CircularCarouselRef>> & {
+    NextTrigger: typeof CircularCarouselNextTrigger;
+    PrevTrigger: typeof CircularCarouselPrevTrigger;
+};
+export declare const CircularCarousel: CircularCarouselComponent;
+export {};

package/dist/components/CircularCarousel/CircularCarouselTriggers.d.ts

@@ -0,0 +1,3 @@
+import type { GroupProps } from "../../types";
+export declare function CircularCarouselNextTrigger(props: GroupProps): import("react/jsx-runtime").JSX.Element;
+export declare function CircularCarouselPrevTrigger(props: GroupProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/CircularCarousel/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const TAU: number;
+export declare const DEFAULT_RADIUS = 3;
+export declare const DEFAULT_AXIS: "y";
+export declare const DEFAULT_DRAG_SENSITIVITY_FACTOR = 280;
+export declare const SPRING_CONFIG: {
+    readonly tension: 200;
+    readonly friction: 25;
+};
+export declare const DRAG_SPRING_CONFIG: {
+    readonly tension: 400;
+    readonly friction: 50;
+};

package/dist/components/CircularCarousel/context.d.ts

@@ -0,0 +1,3 @@
+import type { CarouselContextValue } from "./types";
+export declare const CarouselContext: import("react").Context<CarouselContextValue | null>;
+export declare function useCarouselContext(): CarouselContextValue;

package/dist/components/CircularCarousel/index.d.ts

@@ -0,0 +1,4 @@
+export { CircularCarousel } from "./CircularCarousel";
+export { CircularCarouselNextTrigger, CircularCarouselPrevTrigger, } from "./CircularCarouselTriggers";
+export { useCarouselContext } from "./context";
+export type { CircularCarouselProps, CircularCarouselRef, CarouselContextValue, DragConfig, } from "./types";

package/dist/components/CircularCarousel/types.d.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from "react";
+export type DragConfig = {
+    /** Axis to constrain drag movement. Default: "x" */
+    axis?: "x" | "y";
+    /** Pointer options for drag gesture */
+    pointer?: {
+        touch?: boolean;
+        capture?: boolean;
+        keys?: boolean;
+    };
+    /** Touch action CSS property. Default: "none" */
+    touchAction?: string;
+    /** Threshold in pixels before drag starts */
+    threshold?: number;
+    /** Rubberband effect when dragging past bounds (0-1) */
+    rubberband?: boolean | number;
+};
+export type CircularCarouselProps = {
+    children: ReactNode;
+    radius?: number;
+    axis?: "x" | "y" | "z";
+    index?: number;
+    defaultIndex?: number;
+    onIndexChange?: (index: number) => void;
+    dragEnabled?: boolean;
+    dragSensitivity?: number;
+    /** Axis for drag gesture. Default: "x" */
+    dragAxis?: "x" | "y";
+    /** Additional drag gesture configuration */
+    dragConfig?: DragConfig;
+};
+export type CircularCarouselRef = {
+    next(): void;
+    prev(): void;
+    goTo(index: number): void;
+};
+export type CarouselContextValue = {
+    activeIndex: number;
+    count: number;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+};

package/dist/components/CircularCarousel/utils.d.ts

@@ -0,0 +1,6 @@
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function getItemTransform(index: number, count: number, radius: number, axis: "x" | "y" | "z"): {
+    position: readonly [number, 0, number] | readonly [0, number, number] | readonly [number, number, 0];
+    rotation: readonly [0, number, 0] | readonly [number, 0, 0] | readonly [0, 0, number];
+};
+export declare function calculateShortestPath(currentOffset: number, targetLogical: number): number;

package/dist/components/LinearCarousel/LinearCarousel.d.ts

@@ -0,0 +1,9 @@
+import { type ForwardRefExoticComponent, type RefAttributes } from "react";
+import { LinearCarouselNextTrigger, LinearCarouselPrevTrigger } from "./LinearCarouselTriggers";
+import type { LinearCarouselProps, LinearCarouselRef } from "./types";
+type LinearCarouselComponent = ForwardRefExoticComponent<LinearCarouselProps & RefAttributes<LinearCarouselRef>> & {
+    NextTrigger: typeof LinearCarouselNextTrigger;
+    PrevTrigger: typeof LinearCarouselPrevTrigger;
+};
+export declare const LinearCarousel: LinearCarouselComponent;
+export {};

package/dist/components/LinearCarousel/LinearCarouselTriggers.d.ts

@@ -0,0 +1,3 @@
+import type { GroupProps } from "../../types";
+export declare function LinearCarouselNextTrigger(props: GroupProps): import("react/jsx-runtime").JSX.Element;
+export declare function LinearCarouselPrevTrigger(props: GroupProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/LinearCarousel/constants.d.ts

@@ -0,0 +1,11 @@
+export declare const DEFAULT_GAP = 0.5;
+export declare const DEFAULT_DIRECTION: "horizontal";
+export declare const DEFAULT_DRAG_SENSITIVITY = 150;
+export declare const SPRING_CONFIG: {
+    readonly tension: 200;
+    readonly friction: 25;
+};
+export declare const DRAG_SPRING_CONFIG: {
+    readonly tension: 400;
+    readonly friction: 50;
+};

package/dist/components/LinearCarousel/context.d.ts

@@ -0,0 +1,3 @@
+import type { LinearCarouselContextValue } from "./types";
+export declare const LinearCarouselContext: import("react").Context<LinearCarouselContextValue | null>;
+export declare function useLinearCarouselContext(): LinearCarouselContextValue;

package/dist/components/LinearCarousel/index.d.ts

@@ -0,0 +1,4 @@
+export { LinearCarousel } from "./LinearCarousel";
+export { LinearCarouselNextTrigger, LinearCarouselPrevTrigger, } from "./LinearCarouselTriggers";
+export { useLinearCarouselContext } from "./context";
+export type { LinearCarouselProps, LinearCarouselRef, LinearCarouselContextValue, DragConfig as LinearDragConfig, } from "./types";

package/dist/components/LinearCarousel/types.d.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from "react";
+export type DragConfig = {
+    /** Axis to constrain drag movement */
+    axis?: "x" | "y";
+    /** Pointer options for drag gesture */
+    pointer?: {
+        touch?: boolean;
+        capture?: boolean;
+        keys?: boolean;
+    };
+    /** Touch action CSS property. Default: "none" */
+    touchAction?: string;
+    /** Threshold in pixels before drag starts */
+    threshold?: number;
+    /** Rubberband effect when dragging past bounds (0-1) */
+    rubberband?: boolean | number;
+};
+export type LinearCarouselProps = {
+    children: ReactNode;
+    gap?: number;
+    direction?: "horizontal" | "vertical";
+    index?: number;
+    defaultIndex?: number;
+    onIndexChange?: (index: number) => void;
+    dragEnabled?: boolean;
+    dragSensitivity?: number;
+    /** Axis for drag gesture. Default: derived from direction ("x" for horizontal, "y" for vertical) */
+    dragAxis?: "x" | "y";
+    /** Additional drag gesture configuration */
+    dragConfig?: DragConfig;
+};
+export type LinearCarouselRef = {
+    next(): void;
+    prev(): void;
+    goTo(index: number): void;
+};
+export type LinearCarouselContextValue = {
+    activeIndex: number;
+    count: number;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+};

package/dist/components/LinearCarousel/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function getItemPosition(index: number, gap: number, direction: "horizontal" | "vertical"): readonly [number, number, number];

package/dist/components/index.d.ts

@@ -0,0 +1,4 @@
+export { CircularCarousel, CircularCarouselNextTrigger, CircularCarouselPrevTrigger, useCarouselContext, } from "./CircularCarousel";
+export type { CircularCarouselProps, CircularCarouselRef, CarouselContextValue, DragConfig, } from "./CircularCarousel";
+export { LinearCarousel, LinearCarouselNextTrigger, LinearCarouselPrevTrigger, useLinearCarouselContext, } from "./LinearCarousel";
+export type { LinearCarouselProps, LinearCarouselRef, LinearCarouselContextValue, } from "./LinearCarousel";

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { CircularCarousel, CircularCarouselNextTrigger, CircularCarouselPrevTrigger, useCarouselContext, LinearCarousel, LinearCarouselNextTrigger, LinearCarouselPrevTrigger, useLinearCarouselContext, } from "./components";
+export type { CircularCarouselProps, CircularCarouselRef, CarouselContextValue, LinearCarouselProps, LinearCarouselRef, LinearCarouselContextValue, DragConfig, } from "./components";
+export type { GroupProps } from "./types";

package/dist/react-three-components.js

@@ -0,0 +1,438 @@
+import { jsx as D, jsxs as bt } from "react/jsx-runtime";
+import Ot, { createContext as dt, useContext as St, forwardRef as Pt, useState as Dt, useRef as N, useMemo as et, Children as Lt, isValidElement as rt, useCallback as E, useImperativeHandle as Mt, useEffect as nt } from "react";
+import { useThree as Ft, useFrame as Gt } from "@react-three/fiber";
+import { useSpring as Ut } from "@react-spring/web";
+import { useDrag as kt } from "@use-gesture/react";
+const S = 2 * Math.PI, zt = 3, jt = "y", Bt = 280, Z = {
+  tension: 200,
+  friction: 25
+}, Wt = {
+  tension: 400,
+  friction: 50
+};
+function mt(c, t, u) {
+  return Math.max(t, Math.min(u, c));
+}
+function Xt(c, t, u, r) {
+  const o = c / t * S, l = Math.cos(o) * u, s = Math.sin(o) * u, I = r === "y" ? [s, 0, l] : r === "x" ? [0, l, s] : [l, s, 0], $ = r === "y" ? [0, Math.PI + o, 0] : r === "x" ? [Math.PI + o, 0, 0] : [0, 0, Math.PI + o];
+  return {
+    position: I,
+    rotation: $
+  };
+}
+function pt(c, t) {
+  const u = Math.round((c - t) / S);
+  return t + u * S;
+}
+const wt = dt(null);
+function $t() {
+  const c = St(wt);
+  if (!c)
+    throw new Error("CircularCarousel compound components must be used within CircularCarousel");
+  return c;
+}
+var C = { exports: {} }, ht = {};
+/**
+ * @license React
+ * react-compiler-runtime.production.js
+ *
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+var It;
+function Jt() {
+  if (It) return ht;
+  It = 1;
+  var c = Ot.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE;
+  return ht.c = function(t) {
+    return c.H.useMemoCache(t);
+  }, ht;
+}
+var Rt = {};
+/**
+ * @license React
+ * react-compiler-runtime.development.js
+ *
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+var xt;
+function Kt() {
+  return xt || (xt = 1, process.env.NODE_ENV !== "production" && (function() {
+    var c = Ot.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE;
+    Rt.c = function(t) {
+      var u = c.H;
+      return u === null && console.error(
+        `Invalid hook call. Hooks can only be called inside of the body of a function component. This could happen for one of the following reasons:
+1. You might have mismatching versions of React and the renderer (such as React DOM)
+2. You might be breaking the Rules of Hooks
+3. You might have more than one copy of React in the same app
+See https://react.dev/link/invalid-hook-call for tips about how to debug and fix this problem.`
+      ), u.useMemoCache(t);
+    };
+  })()), Rt;
+}
+var At;
+function Qt() {
+  return At || (At = 1, process.env.NODE_ENV === "production" ? C.exports = Jt() : C.exports = Kt()), C.exports;
+}
+var ot = Qt();
+function vt(c) {
+  const t = ot.c(9), {
+    next: u
+  } = $t();
+  let r, o;
+  t[0] !== c ? ({
+    children: r,
+    ...o
+  } = c, t[0] = c, t[1] = r, t[2] = o) : (r = t[1], o = t[2]);
+  let l;
+  t[3] !== u ? (l = () => u(), t[3] = u, t[4] = l) : l = t[4];
+  let s;
+  return t[5] !== r || t[6] !== o || t[7] !== l ? (s = /* @__PURE__ */ D("group", { onClick: l, ...o, children: r }), t[5] = r, t[6] = o, t[7] = l, t[8] = s) : s = t[8], s;
+}
+function _t(c) {
+  const t = ot.c(9), {
+    prev: u
+  } = $t();
+  let r, o;
+  t[0] !== c ? ({
+    children: r,
+    ...o
+  } = c, t[0] = c, t[1] = r, t[2] = o) : (r = t[1], o = t[2]);
+  let l;
+  t[3] !== u ? (l = () => u(), t[3] = u, t[4] = l) : l = t[4];
+  let s;
+  return t[5] !== r || t[6] !== o || t[7] !== l ? (s = /* @__PURE__ */ D("group", { onClick: l, ...o, children: r }), t[5] = r, t[6] = o, t[7] = l, t[8] = s) : s = t[8], s;
+}
+const Tt = Pt(function({
+  children: t,
+  radius: u = zt,
+  axis: r = jt,
+  index: o,
+  defaultIndex: l = 0,
+  onIndexChange: s,
+  dragEnabled: I = !0,
+  dragSensitivity: $,
+  dragAxis: X = "x",
+  dragConfig: a
+}, st) {
+  const [ct, q] = Dt(l), x = o !== void 0, R = x ? o : ct, p = N(R);
+  p.current = R;
+  const H = et(() => Lt.toArray(t), [t]), Y = H.filter((i) => rt(i) && i.type !== vt && i.type !== _t), ut = H.filter((i) => rt(i) && (i.type === vt || i.type === _t)), n = Y.length, P = N(null), y = n > 0 ? S / n : S, it = $ ?? Bt / y, [{
+    offset: lt
+  }, V] = Ut(() => ({
+    offset: 0
+  })), v = N(V);
+  v.current = V;
+  const z = N(!1), A = N(0), j = N(0), _ = E((i) => {
+    const e = mt(i, 0, n - 1);
+    if (e === p.current) return;
+    p.current = e, x || q(e), s == null || s(e);
+    const f = -(e / n) * S, m = pt(A.current, f);
+    v.current.start({
+      offset: m,
+      config: Z
+    });
+  }, [n, x, s]), b = E(() => {
+    n !== 0 && _((p.current + 1) % n);
+  }, [n, _]), O = E(() => {
+    n !== 0 && _((p.current - 1 + n) % n);
+  }, [n, _]), d = E((i) => _(i), [_]);
+  Mt(st, () => ({
+    next: b,
+    prev: O,
+    goTo: d
+  }), [b, O, d]), nt(() => {
+    if (!z.current && n > 0) {
+      const i = -(R / n) * S, e = A.current, m = e === 0 && R !== 0 ? i : pt(e, i);
+      v.current.start({
+        offset: m,
+        config: Z
+      });
+    }
+  }, [R, n]);
+  const {
+    gl: h
+  } = Ft();
+  kt(({
+    active: i,
+    movement: [e, f],
+    first: m,
+    last: K,
+    event: ft
+  }) => {
+    z.current = i;
+    const G = ft, U = X === "x" ? e : f;
+    if (i && m && G.pointerId != null && (h.domElement.setPointerCapture(G.pointerId), h.domElement.style.cursor = "grabbing", j.current = A.current), !i && K && G.pointerId != null) {
+      try {
+        h.domElement.releasePointerCapture(G.pointerId);
+      } catch {
+      }
+      h.domElement.style.cursor = "grab";
+    }
+    const B = m ? A.current : j.current, k = Number(U), L = Number.isFinite(k) ? mt(k / it, -y, y) : 0;
+    if (i)
+      v.current.start({
+        offset: B + L,
+        config: Wt
+      });
+    else {
+      const M = p.current, W = (M - 1 + n) % n, Q = (M + 1) % n, w = B + L;
+      let T = (Math.round(-w / S * n) % n + n) % n;
+      T !== W && T !== M && T !== Q && (T = L > 0 ? Q : L < 0 ? W : M);
+      const F = mt(T, 0, n - 1);
+      if (n === 0 || !Number.isFinite(F)) {
+        v.current.start({
+          offset: B,
+          config: Z
+        });
+        return;
+      }
+      p.current = F, x || q(F), s == null || s(F);
+      const Yt = -(F / n) * S, Vt = pt(w, Yt);
+      v.current.start({
+        offset: Vt,
+        config: Z
+      });
+    }
+  }, {
+    target: h.domElement,
+    enabled: I,
+    pointer: (a == null ? void 0 : a.pointer) ?? {
+      touch: !0,
+      capture: !0
+    },
+    axis: (a == null ? void 0 : a.axis) ?? X,
+    touchAction: (a == null ? void 0 : a.touchAction) ?? "none",
+    threshold: a == null ? void 0 : a.threshold,
+    rubberband: a == null ? void 0 : a.rubberband
+  }), nt(() => {
+    if (!I) return;
+    const i = h.domElement, e = i.style.touchAction, f = i.style.cursor;
+    return i.style.touchAction = "none", i.style.cursor = "grab", () => {
+      i.style.touchAction = e, i.style.cursor = f;
+    };
+  }, [I, h.domElement]), Gt(() => {
+    if (!P.current) return;
+    const i = lt.get();
+    A.current = i, P.current.rotation[r] = i;
+  });
+  const J = E((i) => Xt(i, n, u, r), [n, u, r]), at = et(() => ({
+    activeIndex: R,
+    count: n,
+    next: b,
+    prev: O,
+    goTo: d
+  }), [R, n, b, O, d]);
+  return /* @__PURE__ */ bt(wt.Provider, { value: at, children: [
+    /* @__PURE__ */ D("group", { ref: P, children: Y.map((i, e) => {
+      const {
+        position: f,
+        rotation: m
+      } = J(e);
+      return /* @__PURE__ */ D("group", { position: f, rotation: m, children: i }, i.key ?? e);
+    }) }),
+    ut
+  ] });
+});
+Tt.NextTrigger = vt;
+Tt.PrevTrigger = _t;
+const ue = Tt, Zt = 0.5, Ct = "horizontal", gt = 150, g = {
+  tension: 200,
+  friction: 25
+}, te = {
+  tension: 400,
+  friction: 50
+};
+function tt(c, t, u) {
+  return Math.max(t, Math.min(u, c));
+}
+function ee(c, t, u) {
+  const r = c * (1 + t);
+  return u === "horizontal" ? [r, 0, 0] : [0, r, 0];
+}
+const qt = dt(null);
+function Ht() {
+  const c = St(qt);
+  if (!c)
+    throw new Error("LinearCarousel compound components must be used within LinearCarousel");
+  return c;
+}
+function yt(c) {
+  const t = ot.c(9), {
+    next: u
+  } = Ht();
+  let r, o;
+  t[0] !== c ? ({
+    children: r,
+    ...o
+  } = c, t[0] = c, t[1] = r, t[2] = o) : (r = t[1], o = t[2]);
+  let l;
+  t[3] !== u ? (l = () => u(), t[3] = u, t[4] = l) : l = t[4];
+  let s;
+  return t[5] !== r || t[6] !== o || t[7] !== l ? (s = /* @__PURE__ */ D("group", { onClick: l, ...o, children: r }), t[5] = r, t[6] = o, t[7] = l, t[8] = s) : s = t[8], s;
+}
+function Nt(c) {
+  const t = ot.c(9), {
+    prev: u
+  } = Ht();
+  let r, o;
+  t[0] !== c ? ({
+    children: r,
+    ...o
+  } = c, t[0] = c, t[1] = r, t[2] = o) : (r = t[1], o = t[2]);
+  let l;
+  t[3] !== u ? (l = () => u(), t[3] = u, t[4] = l) : l = t[4];
+  let s;
+  return t[5] !== r || t[6] !== o || t[7] !== l ? (s = /* @__PURE__ */ D("group", { onClick: l, ...o, children: r }), t[5] = r, t[6] = o, t[7] = l, t[8] = s) : s = t[8], s;
+}
+const Et = Pt(function({
+  children: t,
+  gap: u = Zt,
+  direction: r = Ct,
+  index: o,
+  defaultIndex: l = 0,
+  onIndexChange: s,
+  dragEnabled: I = !0,
+  dragSensitivity: $,
+  dragAxis: X,
+  dragConfig: a
+}, st) {
+  const [ct, q] = Dt(l), x = o !== void 0, R = x ? o : ct, p = N(R);
+  p.current = R;
+  const H = et(() => Lt.toArray(t), [t]), Y = H.filter((e) => rt(e) && e.type !== yt && e.type !== Nt), ut = H.filter((e) => rt(e) && (e.type === yt || e.type === Nt)), n = Y.length, P = N(null), y = 1 + u, it = $ ?? gt, [{
+    offset: lt
+  }, V] = Ut(() => ({
+    offset: 0
+  })), v = N(V);
+  v.current = V;
+  const z = N(!1), A = N(0), j = N(0), _ = E((e) => {
+    const f = tt(e, 0, n - 1);
+    if (f === p.current) return;
+    p.current = f, x || q(f), s == null || s(f);
+    const m = -f * y;
+    v.current.start({
+      offset: m,
+      config: g
+    });
+  }, [n, x, s, y]), b = E(() => {
+    if (n === 0) return;
+    const e = Math.min(p.current + 1, n - 1);
+    _(e);
+  }, [n, _]), O = E(() => {
+    if (n === 0) return;
+    const e = Math.max(p.current - 1, 0);
+    _(e);
+  }, [n, _]), d = E((e) => _(e), [_]);
+  Mt(st, () => ({
+    next: b,
+    prev: O,
+    goTo: d
+  }), [b, O, d]), nt(() => {
+    if (!z.current && n > 0) {
+      const e = -R * y;
+      v.current.start({
+        offset: e,
+        config: g
+      });
+    }
+  }, [R, n, y]);
+  const {
+    gl: h
+  } = Ft(), J = X ?? (r === "horizontal" ? "x" : "y");
+  kt(({
+    active: e,
+    movement: [f, m],
+    first: K,
+    last: ft,
+    event: G
+  }) => {
+    z.current = e;
+    const U = G, B = J === "x" ? f : m;
+    if (e && K && U.pointerId != null && (h.domElement.setPointerCapture(U.pointerId), h.domElement.style.cursor = "grabbing", j.current = A.current), !e && ft && U.pointerId != null) {
+      try {
+        h.domElement.releasePointerCapture(U.pointerId);
+      } catch {
+      }
+      h.domElement.style.cursor = "grab";
+    }
+    const k = K ? A.current : j.current, L = Number(B), M = Number.isFinite(L) ? tt(L / it, -y, y) : 0;
+    if (e)
+      v.current.start({
+        offset: k + M,
+        config: te
+      });
+    else {
+      const W = p.current, Q = k + M;
+      let w = Math.round(-Q / y);
+      w = tt(w, W - 1, W + 1);
+      const T = tt(w, 0, n - 1);
+      if (n === 0 || !Number.isFinite(T)) {
+        v.current.start({
+          offset: k,
+          config: g
+        });
+        return;
+      }
+      p.current = T, x || q(T), s == null || s(T);
+      const F = -T * y;
+      v.current.start({
+        offset: F,
+        config: g
+      });
+    }
+  }, {
+    target: h.domElement,
+    enabled: I,
+    pointer: (a == null ? void 0 : a.pointer) ?? {
+      touch: !0,
+      capture: !0
+    },
+    axis: (a == null ? void 0 : a.axis) ?? J,
+    touchAction: (a == null ? void 0 : a.touchAction) ?? "none",
+    threshold: a == null ? void 0 : a.threshold,
+    rubberband: a == null ? void 0 : a.rubberband
+  }), nt(() => {
+    if (!I) return;
+    const e = h.domElement, f = e.style.touchAction, m = e.style.cursor;
+    return e.style.touchAction = "none", e.style.cursor = "grab", () => {
+      e.style.touchAction = f, e.style.cursor = m;
+    };
+  }, [I, h.domElement]), Gt(() => {
+    if (!P.current) return;
+    const e = lt.get();
+    A.current = e, r === "horizontal" ? P.current.position.x = e : P.current.position.y = e;
+  });
+  const at = E((e) => ee(e, u, r), [u, r]), i = et(() => ({
+    activeIndex: R,
+    count: n,
+    next: b,
+    prev: O,
+    goTo: d
+  }), [R, n, b, O, d]);
+  return /* @__PURE__ */ bt(qt.Provider, { value: i, children: [
+    /* @__PURE__ */ D("group", { ref: P, children: Y.map((e, f) => {
+      const m = at(f);
+      return /* @__PURE__ */ D("group", { position: [...m], children: e }, e.key ?? f);
+    }) }),
+    ut
+  ] });
+});
+Et.NextTrigger = yt;
+Et.PrevTrigger = Nt;
+const ie = Et;
+export {
+  ue as CircularCarousel,
+  vt as CircularCarouselNextTrigger,
+  _t as CircularCarouselPrevTrigger,
+  ie as LinearCarousel,
+  yt as LinearCarouselNextTrigger,
+  Nt as LinearCarouselPrevTrigger,
+  $t as useCarouselContext,
+  Ht as useLinearCarouselContext
+};

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+import type { ThreeElements } from "@react-three/fiber";
+export type GroupProps = ThreeElements["group"];

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@juniorxsound/react-three-components",
+  "version": "0.1.0",
+  "description": "3D carousel components for React Three Fiber",
+  "author": "juniorxsound",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juniorxsound/react-three-components.git"
+  },
+  "keywords": [
+    "react",
+    "three",
+    "threejs",
+    "r3f",
+    "react-three-fiber",
+    "carousel",
+    "3d"
+  ],
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "main": "./dist/react-three-components.js",
+  "module": "./dist/react-three-components.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/react-three-components.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "dev": "storybook dev -p 6006",
+    "build": "tsc && vite build && tsc -p tsconfig.build.json",
+    "build:storybook": "storybook build",
+    "lint": "eslint .",
+    "storybook": "storybook dev -p 6006",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "release:patch": "npm run lint && npm run test:run && npm run build && npm version patch -m 'Release %s' && git push && git push --tags",
+    "release:minor": "npm run lint && npm run test:run && npm run build && npm version minor -m 'Release %s' && git push && git push --tags",
+    "release:major": "npm run lint && npm run test:run && npm run build && npm version major -m 'Release %s' && git push && git push --tags"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "three": ">=0.150.0",
+    "@react-three/fiber": ">=8",
+    "@react-spring/web": ">=9",
+    "@use-gesture/react": ">=10"
+  },
+  "devDependencies": {
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.5.0",
+    "@react-spring/web": "^10.0.3",
+    "@use-gesture/react": "^10.3.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "three": "^0.182.0",
+    "@eslint/js": "^9.39.1",
+    "@react-three/test-renderer": "^9.1.0",
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/react": "^8.6.15",
+    "@storybook/react-vite": "^8.6.15",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "storybook": "^8.6.15",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^6.4.1",
+    "vitest": "^4.0.18"
+  }
+}