@juniorxsound/react-three-components 0.1.1 → 0.1.3

package/README.md

@@ -4,7 +4,9 @@
 [![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.
+A personal set of reusable components for React Three Fiber 🪄
+
+> This library is a work in progress - if you find any issues, please report them [here](https://github.com/juniorxsound/react-three-components/issues). Please proceed with caution if you use this library in production.
 
 ## Installation
 
@@ -28,12 +30,15 @@ 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";
+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]} />
@@ -58,27 +63,27 @@ function App() {
 
 #### 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 |
+| 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
+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
@@ -88,13 +93,19 @@ ref.current.goTo(2);     // Go to specific index
   <Item index={0} />
   <Item index={1} />
   <Item index={2} />
-  
+
   <CircularCarousel.PrevTrigger position={[-2, 0, 0]}>
-    <mesh><boxGeometry /><meshBasicMaterial color="blue" /></mesh>
+    <mesh>
+      <boxGeometry />
+      <meshBasicMaterial color="blue" />
+    </mesh>
   </CircularCarousel.PrevTrigger>
-  
+
   <CircularCarousel.NextTrigger position={[2, 0, 0]}>
-    <mesh><boxGeometry /><meshBasicMaterial color="red" /></mesh>
+    <mesh>
+      <boxGeometry />
+      <meshBasicMaterial color="red" />
+    </mesh>
   </CircularCarousel.NextTrigger>
 </CircularCarousel>
 ```
@@ -107,12 +118,15 @@ A carousel that slides items linearly (horizontally or vertically).
 
 ```tsx
 import { Canvas } from "@react-three/fiber";
-import { LinearCarousel, useLinearCarouselContext } from "@juniorxsound/react-three-components";
+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]} />
@@ -137,27 +151,27 @@ function App() {
 
 #### 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 |
+| 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
+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.
@@ -169,11 +183,11 @@ ref.current.goTo(2);     // Go to specific index
   <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>

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

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

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

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

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

@@ -1,20 +1,6 @@
 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;
-};
+import type { DragConfig, CarouselContextValue } from "../../hooks";
+export type { DragConfig, CarouselContextValue };
 export type CircularCarouselProps = {
     children: ReactNode;
     radius?: number;
@@ -34,10 +20,3 @@ export type CircularCarouselRef = {
     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

@@ -1,4 +1,3 @@
-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];

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

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

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

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

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

@@ -1,20 +1,7 @@
 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;
-};
+import type { DragConfig, CarouselContextValue } from "../../hooks";
+export type { DragConfig };
+export type { CarouselContextValue as LinearCarouselContextValue };
 export type LinearCarouselProps = {
     children: ReactNode;
     gap?: number;
@@ -28,16 +15,11 @@ export type LinearCarouselProps = {
     dragAxis?: "x" | "y";
     /** Additional drag gesture configuration */
     dragConfig?: DragConfig;
+    /** When true, navigation wraps from last item to first and vice versa. Default: false */
+    infinite?: boolean;
 };
 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

@@ -1,2 +1 @@
-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/StorybookUtils/index.d.ts

@@ -0,0 +1,9 @@
+import type React from "react";
+/**
+ * A floating 3D shape for use in carousel stories.
+ * Pass `isActive` to control the float animation.
+ */
+export declare function FloatingShape({ type, isActive, }: {
+    type: "box" | "sphere" | "cone" | "plane";
+    isActive: boolean;
+}): React.ReactNode;

package/dist/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useCarouselDrag, type DragConfig, type SpringConfig, type UseCarouselDragOptions, type UseCarouselDragReturn, } from "./useCarouselDrag";
+export { CarouselContext, useCarouselContext, type CarouselContextValue, } from "./useCarouselContext";

package/dist/hooks/useCarouselContext.d.ts

@@ -0,0 +1,20 @@
+export type CarouselContextValue = {
+    /** Currently active item index */
+    activeIndex: number;
+    /** Total number of items */
+    count: number;
+    /** Navigate to the next item */
+    next: () => void;
+    /** Navigate to the previous item */
+    prev: () => void;
+    /** Navigate to a specific item by index */
+    goTo: (index: number) => void;
+};
+export declare const CarouselContext: import("react").Context<CarouselContextValue | null>;
+/**
+ * Hook to access carousel context from within a carousel component.
+ * @param componentName - Name of the carousel component for error messages
+ * @returns The carousel context value
+ * @throws If used outside of a carousel component
+ */
+export declare function useCarouselContext(componentName: string): CarouselContextValue;

package/dist/hooks/useCarouselDrag.d.ts

@@ -0,0 +1,85 @@
+import { type SpringRef } from "@react-spring/web";
+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. Default: 5 */
+    threshold?: number;
+    /** Rubberband effect when dragging past bounds (0-1) */
+    rubberband?: boolean | number;
+    /** Filter out taps (clicks) from drags. Default: true */
+    filterTaps?: boolean;
+};
+export type SpringConfig = {
+    tension: number;
+    friction: number;
+};
+export type UseCarouselDragOptions = {
+    /** Number of items in the carousel */
+    count: number;
+    /** Whether drag is enabled */
+    dragEnabled: boolean;
+    /** Axis for drag gesture ("x" or "y") */
+    dragAxis: "x" | "y";
+    /** Sensitivity for drag movement (pixels per unit) */
+    dragSensitivity: number;
+    /** Maximum drag amount per gesture (e.g., itemSpacing or anglePerItem) */
+    maxDragAmount: number;
+    /** Additional drag configuration */
+    dragConfig?: DragConfig;
+    /** Spring configuration for settling animations */
+    springConfig: SpringConfig;
+    /** Spring configuration for drag animations */
+    dragSpringConfig: SpringConfig;
+    /**
+     * Calculate the nearest index from an offset value.
+     * @param offset - The current offset value
+     * @returns The nearest index
+     */
+    calculateIndexFromOffset: (offset: number) => number;
+    /**
+     * Calculate the final target index after drag ends.
+     * @param currentOffset - The offset at drag end
+     * @param startIndex - The index when drag started
+     * @param dragAmount - The clamped drag amount
+     * @returns The target index to navigate to
+     */
+    calculateTargetIndex: (currentOffset: number, startIndex: number, dragAmount: number) => number;
+    /**
+     * Calculate the target offset for an index.
+     * @param index - The target index
+     * @param currentOffset - The current offset (useful for shortest path calculations)
+     * @returns The target offset value
+     */
+    calculateTargetOffset: (index: number, currentOffset: number) => number;
+    /**
+     * Called when navigation completes with the final index.
+     */
+    onNavigate: (index: number) => void;
+};
+export type UseCarouselDragReturn = {
+    /** Spring offset value */
+    offset: {
+        get: () => number;
+    };
+    /** Spring API for manual control */
+    springApi: SpringRef<{
+        offset: number;
+    }>;
+    /** Ref tracking if currently dragging */
+    isDraggingRef: React.MutableRefObject<boolean>;
+    /** Ref tracking current offset value (updated each frame) */
+    currentOffsetRef: React.MutableRefObject<number>;
+};
+/**
+ * Shared hook for carousel drag behavior.
+ * Handles spring animation, gesture recognition, and cursor management.
+ */
+export declare function useCarouselDrag(options: UseCarouselDragOptions): UseCarouselDragReturn;