@vctrl/hooks 0.0.9-4 → 0.0.9

package/.babelrc

@@ -0,0 +1,12 @@
+{
+  "presets": [
+    [
+      "@nx/react/babel",
+      {
+        "runtime": "automatic",
+        "useBuiltIns": "usage"
+      }
+    ]
+  ],
+  "plugins": []
+}

package/.eslintrc.json

@@ -0,0 +1,18 @@
+{
+  "extends": ["plugin:@nx/react", "../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,209 @@
+# vctrl/hooks
+
+[![Version and release packages to NPM](https://img.shields.io/github/actions/workflow/status/vectreal/vectreal-core/version-release.yaml?logo=github&logoColor=%23fc6c18&label=Version%20and%20release%20packages%20to%20NPM&color=%23fc6c18)
+](https://github.com/Vectreal/vectreal-core/actions/workflows/version-release.yaml)
+[![@vctrl/hooks | NPM Downloads](https://img.shields.io/npm/dm/%40vctrl%2Fhooks?logo=npm&logoColor=%23fc6c18&label=%40vctrl%2Fhooks%20%7C%20NPM%20Downloads&color=%23fc6c18)](https://www.npmjs.com/package/@vctrl/hooks)
+
+## Overview
+
+vctrl/hooks is a React hooks package designed to simplify 3D model loading and management within React applications. It's part of the vectreal-core ecosystem and is primarily used in the vctrl/viewer React component and the official website application.
+
+The package provides a powerful hook for loading various 3D model file formats, along with a React context for easy state management and an event system for handling different stages of the model loading process.
+
+## Table of contents
+
+- [vctrl/hooks](#vctrlhooks)
+  - [Overview](#overview)
+  - [Table of contents](#table-of-contents)
+  - [Features](#features)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [API Reference](#api-reference)
+    - [useLoadModel](#useloadmodel)
+      - [Returns](#returns)
+    - [ModelContext](#modelcontext)
+    - [Event System](#event-system)
+      - [Events](#events)
+  - [Supported File Types](#supported-file-types)
+  - [File Loading Process](#file-loading-process)
+  - [State Management](#state-management)
+  - [Integration with Three.js](#integration-with-threejs)
+  - [Development](#development)
+  - [License](#license)
+  - [Contributing](#contributing)
+  - [Support](#support)
+
+## Features
+
+- Direct 3D model file loading (supports GLTF, GLB, and USDZ formats)
+- React context for state management (ModelContext)
+- Event system for handling loading progress and completion
+- Three.js integration
+- TypeScript support
+
+## Installation
+
+To install the package, use npm or yarn:
+
+```bash
+npm install @vctrl/hooks
+# or
+yarn add @vctrl/hooks
+```
+
+## Usage
+
+The main hook exported by this package is `useLoadModel`. Here's a basic example of how to use it:
+
+```jsx
+import React from 'react';
+import { useLoadModel } from '@vctrl/hooks/use-load-model';
+
+function ModelLoader() {
+  const { handleFileUpload, file, progress, isLoading } = useLoadModel();
+
+  const onFileChange = (event) => {
+    const files = Array.from(event.target.files);
+    handleFileUpload(files);
+  };
+
+  return (
+    <div>
+      <input type="file" onChange={onFileChange} />
+      {isLoading && <p>Loading: {progress}%</p>}
+      {file && <p>Model loaded: {file.name}</p>}
+    </div>
+  );
+}
+```
+
+> Multiple files can be handled, e.g. when uploading a `.gltf` model, its `.bin` file and the relavant image texture files as `.jpeg`/`.png` (Other texture file formats have not been tested).
+
+## API Reference
+
+### useLoadModel
+
+The main hook for loading and managing 3D model files.
+
+#### Returns
+
+- `file`: The loaded file object of type `ModelFile | null`.
+- `isLoading`: A boolean indicating whether a file is currently being loaded.
+- `progress`: A number between 0 and 100 representing the loading progress.
+- `handleFileUpload`: A function to handle file upload. It accepts an array of `File` objects or a mixed array of `File` objects and directory entries.
+- `on`: A function to subscribe to events.
+- `off`: A function to unsubscribe from events.
+
+### ModelContext
+
+A React context that provides the state and functions from `useLoadModel` to child components. It's implemented in `model-context.tsx`.
+
+```jsx
+import { ModelProvider, useModelContext } from '@vctrl/hooks/use-load-model';
+
+function App() {
+  return (
+    <ModelProvider>
+      <ModelConsumer />
+    </ModelProvider>
+  );
+}
+
+function ModelConsumer() {
+  const { file, isLoading, progress, handleFileUpload } = useModelContext();
+  // Use the context values
+}
+```
+
+> When using the React Context, only load models with the `useModelContext` hook.
+
+### Event System
+
+The package includes a custom event system for handling various stages of the model loading process. The event system is implemented in `event-system.ts` and provides three main methods:
+
+- `emit<T extends EventTypes>(event: T, data: EventData[T]): void`
+- `on<T extends EventTypes>(event: T, handler: EventHandler<T>): void`
+- `off<T extends EventTypes>(event: T, handler: EventHandler<T>): void`
+
+#### Events
+
+You can subscribe to these events using the `on` method:
+
+- `'UPLOAD_PROGRESS'`: Emitted with the current progress (0-100) during file upload.
+- `'UPLOAD_COMPLETE'`: Emitted with the loaded file object when the upload is complete.
+- `'MULTIPLE_3D_MODELS'`: Emitted if multiple supported 3D model files are detected in the upload.
+- `'UNSUPPORTED_FILE_TYPE'`: Emitted if an unsupported file type is uploaded.
+
+Example usage:
+
+```javascript
+const { on, off } = useLoadModel();
+
+useEffect(() => {
+  const handleProgress = (progress) => {
+    console.log(`Upload progress: ${progress}%`);
+  };
+
+  on('UPLOAD_PROGRESS', handleProgress);
+
+  return () => off('UPLOAD_PROGRESS', handleProgress);
+}, [on, off]);
+```
+
+## Supported File Types
+
+The package currently supports the following 3D model file formats:
+
+- GLTF (.gltf)
+- GLB (.glb)
+- USDZ (.usdz)
+
+These are defined in the `ModelFileTypes` enum in `types.ts`.
+
+## File Loading Process
+
+The file loading process, particularly for GLTF files, is handled by the `useLoadGltf` hook in `use-load-gltf.ts`. This hook performs the following steps:
+
+1. Parses the GLTF file content.
+2. Embeds external resources (buffers and images) into the GLTF content.
+3. Uses Three.js GLTFLoader to parse the modified GLTF content.
+4. Dispatches actions to update the state with the loaded model.
+
+The loading process includes progress updates, which are communicated through the event system.
+
+## State Management
+
+The package uses a reducer pattern for state management, implemented in `state.ts`. The state includes:
+
+- `file`: The currently loaded model file.
+- `isFileLoading`: A boolean indicating if a file is being loaded.
+- `progress`: The current loading progress.
+- `supportedFileTypes`: An array of supported file types.
+
+Actions for updating the state are defined in the `Action` type in `types.ts`.
+
+## Integration with Three.js
+
+The package integrates with Three.js for handling 3D model rendering. The loaded models are compatible with Three.js scene rendering, with the model stored as a Three.js `Object3D` in the `ModelFile` interface.
+
+## Development
+
+This package is part of a monorepo workspace managed with Nx. To contribute or modify the package:
+
+1. Clone the monorepo
+2. Install dependencies: `npm install` or `yarn install`
+3. Make your changes
+4. Build the package: `nx build vctrl/hooks`
+5. Test your changes: `nx test vctrl/hooks`
+
+## License
+
+Please refer to the LICENSE file in the package root for licensing information.
+
+## Contributing
+
+Contributions are welcome! Please read the contributing guidelines in the [vectreal-core](https://github.com/vectreal/vectreal-core) monorepo before submitting pull requests.
+
+## Support
+
+For issues, feature requests, or questions, please file an issue in the GitHub repository.

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.9-4",
+  "version": "0.0.9",
   "name": "@vctrl/hooks",
   "description": "vctrl/hooks is a React hooks package designed to simplify 3D model loading and management within React applications. It's part of the vectreal-core ecosystem and is primarily used in the vctrl/viewer React component and the official website application.",
   "bugs": {

package/project.json

@@ -0,0 +1,16 @@
+{
+  "name": "vctrl/hooks",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/hooks/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/vite:build",
+      "options": {
+        "outputPath": "dist/packages/vctrl/hooks",
+        "configFile": "packages/hooks/vite.config.ts"
+      }
+    }
+  }
+}

package/src/use-load-model/event-system.ts

@@ -0,0 +1,29 @@
+import { EventData, EventHandler, EventTypes } from './types';
+
+const listeners = {} as Record<EventTypes, EventHandler<EventTypes>[]>;
+const eventSystem = {
+  emit<T extends EventTypes>(event: T, data: EventData[T]): void {
+    const handlers = listeners[event];
+    if (handlers) {
+      handlers.forEach((handler) => handler(data));
+    }
+  },
+
+  on<T extends EventTypes>(event: T, handler: EventHandler<T>): void {
+    if (!listeners[event]) {
+      listeners[event] = [];
+    }
+    listeners[event].push(handler as EventHandler<EventTypes>);
+  },
+
+  off<T extends EventTypes>(event: T, handler: EventHandler<T>): void {
+    const handlers = listeners[event];
+    if (handlers) {
+      listeners[event] = handlers.filter(
+        (h) => h !== handler,
+      ) as EventHandler<EventTypes>[];
+    }
+  },
+};
+
+export default eventSystem;

package/src/use-load-model/file-type-hooks/use-load-binary.ts

@@ -0,0 +1,74 @@
+import { useCallback } from 'react';
+
+import { Action, ModelFileTypes } from '../types';
+import { createGltfLoader, createUsdzLoader } from '../loaders';
+
+/**
+ * Hook to load binary files
+ *
+ * @param dispatch - The dispatch function from the useReducer hook
+ * @returns An object containing the loadBinary function
+ */
+function useLoadBinary(dispatch: React.Dispatch<Action>) {
+  /**
+   * Function to read binary files
+   *
+   * @param file - The binary file to read
+   * @param fileType - The type of file to read
+   * @param onProgress - The function to call when progress is made
+   * @returns {void}
+   */
+  const loadBinary = useCallback(
+    (file: File, fileType: ModelFileTypes, onProgress: () => void) => {
+      const reader = new FileReader();
+
+      reader.onload = async (event: ProgressEvent<FileReader>) => {
+        if (event.target?.result) {
+          const arrayBuffer = event.target.result as ArrayBuffer;
+
+          if (fileType === ModelFileTypes.glb) {
+            const gltfLoader = createGltfLoader();
+
+            gltfLoader.parse(arrayBuffer, '', (gltf) => {
+              dispatch({
+                type: 'SET_FILE',
+                payload: {
+                  model: gltf.scene,
+                  type: ModelFileTypes.glb,
+                  name: file.name,
+                },
+              });
+            });
+          } else if (fileType === ModelFileTypes.usdz) {
+            const usdzLoader = createUsdzLoader();
+            const model = usdzLoader.parse(arrayBuffer);
+
+            dispatch({
+              type: 'SET_FILE',
+              payload: {
+                model: model,
+                type: ModelFileTypes.usdz,
+                name: file.name,
+              },
+            });
+          }
+
+          onProgress(); // Call progress callback when binary file is loaded
+          dispatch({ type: 'SET_FILE_LOADING', payload: false });
+        }
+      };
+
+      reader.onerror = (error) => {
+        console.error('Error reading file:', error);
+        dispatch({ type: 'SET_FILE_LOADING', payload: false });
+      };
+
+      reader.readAsArrayBuffer(file);
+    },
+    [dispatch],
+  );
+
+  return { loadBinary };
+}
+
+export default useLoadBinary;

package/src/use-load-model/file-type-hooks/use-load-gltf.ts

@@ -0,0 +1,115 @@
+import { useCallback } from 'react';
+
+import { Action, ModelFileTypes, ReducedGltf } from '../types';
+import { arrayBufferToBase64 } from '../utils';
+import { createGltfLoader } from '../loaders';
+
+function useLoadGltf(dispatch: React.Dispatch<Action>) {
+  const embedExternalResources = useCallback(
+    async (
+      gltfContent: ReducedGltf,
+      otherFiles: File[],
+      onProgress: (progress: number) => void,
+    ) => {
+      const fileMap = new Map(otherFiles.map((file) => [file.name, file]));
+      const totalFiles =
+        (gltfContent.buffers?.length || 0) + (gltfContent.images?.length || 0);
+      let processedFiles = 0;
+
+      const updateProgress = () => {
+        processedFiles++;
+        onProgress((processedFiles / totalFiles) * 100);
+      };
+
+      // Embed buffers
+      if (gltfContent.buffers) {
+        for (let i = 0; i < gltfContent.buffers.length; i++) {
+          const buffer = gltfContent.buffers[i];
+          if (!buffer.uri || buffer.uri.startsWith('data:')) {
+            updateProgress();
+            continue;
+          }
+
+          const fileName = buffer.uri.split('/').pop() || '';
+          const file = fileMap.get(fileName);
+          if (file) {
+            const arrayBuffer = await file.arrayBuffer();
+            const base64 = await arrayBufferToBase64(arrayBuffer);
+            buffer.uri = `data:application/octet-stream;base64,${base64}`;
+          }
+          updateProgress();
+        }
+      }
+
+      // Embed images
+      if (gltfContent.images) {
+        for (let i = 0; i < gltfContent.images.length; i++) {
+          const image = gltfContent.images[i];
+          if (!image.uri || image.uri.startsWith('data:')) {
+            updateProgress();
+            continue;
+          }
+
+          const fileName = image.uri.split('/').pop() || '';
+          const file = fileMap.get(fileName);
+          if (file) {
+            const arrayBuffer = await file.arrayBuffer();
+            const base64 = await arrayBufferToBase64(arrayBuffer);
+            const mimeType = file.type || 'image/png';
+            image.uri = `data:${mimeType};base64,${base64}`;
+          }
+          updateProgress();
+        }
+      }
+
+      return gltfContent;
+    },
+    [],
+  );
+
+  const loadGltf = useCallback(
+    (
+      gltfFile: File,
+      otherFiles: File[],
+      onProgress: (progress: number) => void,
+    ) => {
+      const reader = new FileReader();
+      reader.onload = async (e) => {
+        const gltfContent = JSON.parse(e.target?.result as string);
+        onProgress(10); // Initial progress after parsing GLTF
+
+        const modifiedGLTF = await embedExternalResources(
+          gltfContent,
+          otherFiles,
+          (embeddingProgress) => {
+            // Map embedding progress to 10-90% range
+            onProgress(10 + embeddingProgress * 0.8);
+          },
+        );
+
+        const gltfLoader = createGltfLoader();
+
+        gltfLoader.parse(JSON.stringify(modifiedGLTF), '', (gltf) => {
+          dispatch({
+            type: 'SET_FILE',
+            payload: {
+              model: gltf.scene,
+              type: ModelFileTypes.gltf,
+              name: gltfFile.name,
+            },
+          });
+        });
+
+        onProgress(100); // Final progress
+        dispatch({ type: 'SET_FILE_LOADING', payload: false });
+      };
+
+      reader.readAsText(gltfFile);
+    },
+    [dispatch, embedExternalResources],
+  );
+
+  return { loadGltf };
+}
+
+export default useLoadGltf;

package/src/use-load-model/loaders/create-gltf-loader.ts

@@ -0,0 +1,20 @@
+import { WebGLRenderer } from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader';
+import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader';
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader';
+
+function createGltfLoader() {
+  const dracoLoader = new DRACOLoader();
+  dracoLoader.setDecoderPath('/draco/');
+
+  const ktxLoader = new KTX2Loader();
+  ktxLoader.setTranscoderPath('/draco/');
+
+  const gltfLoader = new GLTFLoader()
+    .setDRACOLoader(dracoLoader)
+    .setKTX2Loader(ktxLoader.detectSupport(new WebGLRenderer()));
+
+  return gltfLoader;
+}
+
+export default createGltfLoader;

package/{use-load-model/loaders/create-usdz-loader.d.ts → src/use-load-model/loaders/create-usdz-loader.ts}

@@ -1,3 +1,9 @@
 import { USDZLoader } from 'three/examples/jsm/loaders/USDZLoader';
-declare function createUsdzLoader(): USDZLoader;
+
+function createUsdzLoader() {
+  const usdzLoader = new USDZLoader();
+
+  return usdzLoader;
+}
+
 export default createUsdzLoader;

package/src/use-load-model/model-context.tsx

@@ -0,0 +1,18 @@
+import { createContext, useContext } from 'react';
+import useLoadModel from './use-load-model';
+
+const ModelContext = createContext({} as ReturnType<typeof useLoadModel>);
+
+const ModelProvider = ({ children }: React.PropsWithChildren) => {
+  const value = useLoadModel();
+
+  return (
+    <ModelContext.Provider value={value}>{children}</ModelContext.Provider>
+  );
+};
+
+const useModelContext = () => {
+  return useContext(ModelContext);
+};
+
+export { ModelContext, ModelProvider, useModelContext };

package/src/use-load-model/state.ts

@@ -0,0 +1,33 @@
+import { Action, ModelFileTypes, State } from './types';
+
+// Initial state
+export const initialState: State = {
+  file: null,
+  isFileLoading: false,
+  progress: 0,
+  supportedFileTypes: Object.values(ModelFileTypes),
+};
+
+/**
+ * Reducer function for the useReadModelFiles hook
+ *
+ * @param state - The current state of the reducer
+ * @param action - The action to be performed
+ * @returns The updated state
+ */
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'SET_FILE':
+      return { ...state, file: action.payload };
+    case 'SET_FILE_LOADING':
+      return { ...state, isFileLoading: action.payload };
+    case 'SET_PROGRESS':
+      return { ...state, progress: action.payload };
+    case 'RESET_STATE':
+      return { ...initialState };
+    default:
+      return state;
+  }
+}
+
+export default reducer;

package/src/use-load-model/types.ts

@@ -0,0 +1,53 @@
+import { Object3D } from 'three';
+
+export enum ModelFileTypes {
+  gltf = 'gltf',
+  glb = 'glb',
+  usdz = 'usdz',
+}
+
+export type InputFileOrDirectory = (File | FileSystemDirectoryHandle)[];
+
+export interface ReducedGltf {
+  images: { name: string; uri: string }[];
+  buffers: { bytelength: string; uri: string }[];
+}
+
+export interface ModelFile {
+  model: Object3D;
+  type: ModelFileTypes;
+  name: string;
+}
+
+// Updated State interface
+export interface State {
+  file: ModelFile | null;
+  isFileLoading: boolean;
+  progress: number;
+  supportedFileTypes: ModelFileTypes[];
+}
+
+// Updated Action types
+export type Action =
+  | { type: 'SET_FILE'; payload: ModelFile }
+  | { type: 'SET_FILE_LOADING'; payload: boolean }
+  | { type: 'SET_PROGRESS'; payload: number }
+  | { type: 'RESET_STATE' };
+
+// Updated Event types
+export type EventTypes =
+  | 'MULTIPLE_3D_MODELS'
+  | 'UNSUPPORTED_FILE_TYPE'
+  | 'UPLOAD_PROGRESS'
+  | 'UPLOAD_COMPLETE';
+
+// Updated event data types
+export type EventData = {
+  MULTIPLE_3D_MODELS: File[];
+  UNSUPPORTED_FILE_TYPE: File[];
+  UPLOAD_PROGRESS: number;
+  UPLOAD_COMPLETE: State['file'];
+};
+
+// Updated EventHandler type
+export type EventHandler<T extends EventTypes> = (data: EventData[T]) => void;