@juniorxsound/react-three-components 0.1.2 → 0.1.4

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>
@@ -182,6 +196,49 @@ ref.current.goTo(2);     // Go to specific index
 
 ---
 
+### useGLTFMaterialVariants
+
+Parse and assign [KHR_materials_variants](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_materials_variants) on an already-loaded glTF. Load the model with `useGLTF` (Drei), `useLoader(GLTFLoader, url)`, or your own loader; then pass the result. The hook applies the first variant initially (or pass `{ variant: "name" }` to avoid flashing). Returns `variants`, `activeVariant`, and `setVariant`. Suspends until the variant is applied—wrap in a `<Suspense>` boundary.
+
+```tsx
+import { Suspense } from "react";
+import { Canvas } from "@react-three/fiber";
+import { useGLTF } from "@react-three/drei";
+import { useGLTFMaterialVariants } from "@juniorxsound/react-three-components";
+
+function Shoe() {
+  const gltf = useGLTF("/MaterialsVariantsShoe.gltf");
+  const { variants, activeVariant, setVariant } = useGLTFMaterialVariants(
+    gltf,
+    { variant: "midnight" }
+  );
+  return (
+    <group>
+      <primitive object={gltf.scene} />
+      {/* Use setVariant(name) to switch variants */}
+    </group>
+  );
+}
+
+function App() {
+  return (
+    <Canvas>
+      <Suspense fallback={null}>
+        <Shoe />
+      </Suspense>
+    </Canvas>
+  );
+}
+```
+
+| Return        | Type       | Description                          |
+| ------------- | ---------- | ------------------------------------ |
+| `variants`    | `string[]` | Variant names from the extension.    |
+| `activeVariant` | `string \| null` | Currently active variant name. |
+| `setVariant`  | `(name: string) => void` | Switch to a variant by name. |
+
+---
+
 ## Context Hooks
 
 Access carousel state from any child component:

package/dist/hooks/index.d.ts

@@ -1,2 +1,3 @@
 export { useCarouselDrag, type DragConfig, type SpringConfig, type UseCarouselDragOptions, type UseCarouselDragReturn, } from "./useCarouselDrag";
 export { CarouselContext, useCarouselContext, type CarouselContextValue, } from "./useCarouselContext";
+export { useGLTFMaterialVariants, type GLTFWithVariants, type UseGLTFMaterialVariantsOptions, type UseGLTFMaterialVariantsResult, } from "./useGLTFMaterialVariants";

package/dist/hooks/useGLTFMaterialVariants.d.ts

@@ -0,0 +1,62 @@
+import type { Group, Mesh } from "three";
+/** KHR_materials_variants extension on the root glTF result. */
+type VariantsExtension = {
+    variants: Array<{
+        name: string;
+    }>;
+};
+/**
+ * glTF result from useGLTF (Drei), useLoader(GLTFLoader, url), or GLTFLoader.loadAsync.
+ * Must include parser and userData.gltfExtensions for KHR_materials_variants.
+ */
+export type GLTFWithVariants = {
+    scene: Group;
+    parser: {
+        getDependency: (type: string, index: number) => Promise<unknown>;
+        assignFinalMaterial: (mesh: Mesh) => void;
+    };
+    userData: {
+        gltfExtensions?: Record<string, VariantsExtension>;
+    };
+};
+/** Options for useGLTFMaterialVariants. */
+export type UseGLTFMaterialVariantsOptions = {
+    /**
+     * Initial variant to apply on first load. Prevents flashing the first variant
+     * before switching. Defaults to the first variant in the model if omitted.
+     */
+    variant?: string;
+    /**
+     * Override for getVariantPromise (testing only). When provided, used instead
+     * of the default implementation so tests can avoid suspending.
+     */
+    getVariantPromise?: (gltf: GLTFWithVariants, variantName: string) => Promise<{
+        variantName: string;
+    }>;
+};
+/** Return value of useGLTFMaterialVariants. */
+export type UseGLTFMaterialVariantsResult = {
+    /** Variant names from the extension, or empty if no extension. */
+    variants: string[];
+    /** Currently active variant name, or null if no variants. */
+    activeVariant: string | null;
+    /** Switch to a variant by name. Suspends until the variant is applied. */
+    setVariant: (variantName: string) => void;
+};
+/** Used internally and for testing. */
+export declare function getVariantsExtension(gltf: GLTFWithVariants): VariantsExtension | null;
+/**
+ * Parse and assign KHR_materials_variants on an already-loaded glTF.
+ * Load the model with useGLTF (Drei), useLoader(GLTFLoader, url), or your own
+ * loader; then pass the result here. Pass options.variant for the initial
+ * variant to avoid flashing. Call setVariant(name) to switch—both initial
+ * apply and setVariant suspend until the variant is applied. Wrap in a React
+ * Suspense boundary.
+ *
+ * @see https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_materials_variants
+ * @param gltf - Loaded glTF (from useGLTF, useLoader(GLTFLoader, url), etc.)
+ * @param options - Optional initial variant (prevents flash on load)
+ * @returns variants, activeVariant, and setVariant (render gltf.scene yourself)
+ */
+export declare function useGLTFMaterialVariants(gltf: GLTFWithVariants, options?: UseGLTFMaterialVariantsOptions): UseGLTFMaterialVariantsResult;
+export {};

package/dist/index.d.ts

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