@vctrl/hooks 0.9.5 → 0.16.2

package/package.json

@@ -1,57 +1,68 @@
 {
-  "version": "0.9.5",
-  "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": {
-    "url": "https://github.com/vectreal/vectreal-core/issues"
-  },
-  "homepage": "https://core.vectreal.com",
-  "keywords": [
-    "vectreal",
-    "react",
-    "3d",
-    "model",
-    "viewer",
-    "react-component",
-    "react-three-fiber",
-    "react-three-drei",
-    "threejs",
-    "react-three-gltf",
-    "gltf",
-    "glb",
-    "usdz",
-    "three-model-loading",
-    "model-viewer"
-  ],
-  "repository": {
-    "url": "https://github.com/vectreal/vectreal-core",
-    "type": "https"
-  },
-  "license": "AGPL-3.0-only",
-  "main": "./index.cjs.js",
-  "module": "./index.es.js",
-  "types": "./index.d.ts",
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "exports": {
-    "./use-load-model": {
-      "import": "./use-load-model.es.js",
-      "require": "./use-load-model.cjs.js",
-      "types": "./use-load-model/index.d.ts"
-    }
-  },
-  "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0"
-  },
-  "dependencies": {
-    "@gltf-transform/core": "^4.0.8",
-    "@gltf-transform/extensions": "^4.0.10",
-    "@gltf-transform/functions": "^4.0.8",
-    "file-saver": "^2.0.5",
-    "jszip": "^3.10.1",
-    "meshoptimizer": "^0.21.0",
-    "three": "^0.168.0"
-  }
+	"version": "0.16.2",
+	"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": {
+		"url": "https://github.com/vectreal/vectreal-platform/issues"
+	},
+	"homepage": "https://vectreal.com",
+	"keywords": [
+		"vectreal",
+		"react",
+		"3d",
+		"model",
+		"viewer",
+		"react-component",
+		"react-three-fiber",
+		"react-three-drei",
+		"threejs",
+		"react-three-gltf",
+		"gltf",
+		"glb",
+		"usdz",
+		"three-model-loading",
+		"model-viewer"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/vectreal/vectreal-platform.git"
+	},
+	"license": "AGPL-3.0-only",
+	"types": "./index.d.ts",
+	"main": "./index.cjs.js",
+	"module": "./index.es.js",
+	"type": "module",
+	"publishConfig": {
+		"access": "public"
+	},
+	"exports": {
+		"./use-load-model": {
+			"types": "./use-load-model/index.d.ts",
+			"import": "./use-load-model.es.js",
+			"require": "./use-load-model.cjs.js"
+		},
+		"./use-export-model": {
+			"types": "./use-export-model/index.d.ts",
+			"import": "./use-export-model.es.js",
+			"require": "./use-export-model.cjs.js"
+		},
+		"./use-optimize-model": {
+			"types": "./use-optimize-model/index.d.ts",
+			"import": "./use-optimize-model.es.js",
+			"require": "./use-optimize-model.cjs.js"
+		}
+	},
+	"peerDependencies": {
+		"react": "^18.0.0 || ^19.0.0",
+		"@gltf-transform/core": "^4.0.8",
+		"file-saver": "^2.0.5",
+		"@nx/vite": "22.5.0",
+		"@vitejs/plugin-react": "^4.3.4",
+		"vite": "^7.3.1",
+		"vite-plugin-dts": "4.5.3"
+	},
+	"dependencies": {
+		"@vctrl/core": "workspace:*",
+		"three": "^0.177.0"
+	}
 }

package/project.json

@@ -0,0 +1,55 @@
+{
+	"name": "vctrl/hooks",
+	"$schema": "../../node_modules/nx/schemas/project-schema.json",
+	"sourceRoot": "packages/hooks/src",
+	"projectType": "library",
+	"tags": [],
+	"targets": {
+		"lint": {
+			"executor": "@nx/eslint:lint",
+			"outputs": ["{options.outputFile}"],
+			"options": {
+				"fix": true,
+				"lintFilePatterns": [
+					"packages/hooks/**/*.{ts,tsx,js,jsx}",
+					"packages/hooks/package.json"
+				]
+			}
+		},
+		"publish": {
+			"dependsOn": ["copy-md"],
+			"executor": "nx:run-commands",
+			"outputs": [],
+			"options": {
+				"command": "npm publish --access public",
+				"cwd": "build/packages/vctrl/hooks"
+			}
+		},
+		"copy-md": {
+			"dependsOn": ["build"],
+			"executor": "nx:run-commands",
+			"outputs": [],
+			"options": {
+				"commands": [
+					"rsync -rat packages/hooks/*.md build/packages/vctrl/hooks/"
+				]
+			}
+		},
+		"build": {
+			"executor": "@nx/vite:build",
+			"outputs": ["{options.outputPath}"],
+			"options": {
+				"outputPath": "build/packages/vctrl/hooks",
+				"configFile": "packages/hooks/vite.config.ts"
+			}
+		},
+		"build-ci": {
+			"executor": "@nx/vite:build",
+			"outputs": ["{options.outputPath}"],
+			"options": {
+				"outputPath": "build/packages/vctrl/hooks",
+				"configFile": "packages/hooks/vite.config.ts"
+			}
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/* vectreal-core | vctrl/hooks
+Copyright (C) 2024 Moritz Becker
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>. */
+
+// Export hooks
+export { default as useLoadModel } from './use-load-model/use-load-model'
+export { default as useExportModel } from './use-export-model/use-export-model'
+export { default as useOptimizeModel } from './use-optimize-model/use-optimize-model'
+
+// Export utilities
+export { reconstructGltfFiles } from './use-load-model/utils/reconstruct-files'
+export { ServerCommunicationService } from './utils/server-communication'
+export type { ServerRequestConfig } from './utils/server-communication'
+
+// Re-export types for convenience
+export type {
+	EventTypes,
+	EventHandler,
+	ModelFile,
+	LoadData,
+	UseLoadModelReturn,
+	SceneDataLoadOptions,
+	SceneLoadOptions,
+	ServerSceneData,
+	SceneLoadResult
+} from './use-load-model/types'

package/src/use-export-model/use-export-model.ts

@@ -0,0 +1,113 @@
+import { Document } from '@gltf-transform/core'
+import { ModelExporter } from '@vctrl/core/model-exporter'
+import fileSaver from 'file-saver'
+import { useCallback, useRef } from 'react'
+
+import { ModelFile } from '../use-load-model'
+
+/**
+ * A React hook for exporting a 3D model using the core ModelExporter.
+ *
+ * @param {Function} [onSaved] Called when the export is complete.
+ * @param {Function} [onError] Called when an error occurs during exporting.
+ * @returns An object with export functions.
+ */
+const useExportModel = (
+	onSaved?: () => void,
+	onError?: (error: Error) => void
+) => {
+	const exporterRef = useRef<ModelExporter>(new ModelExporter())
+
+	const handleThreeGltfExport = useCallback(
+		async (file: ModelFile | null, binary: boolean): Promise<void> => {
+			const scene = file?.model
+			if (!scene) {
+				console.error('Scene not initialized')
+				return
+			}
+
+			try {
+				const exporter = exporterRef.current
+				const baseFileName = file.name.replace(/\.[^/.]+$/, '') // Remove extension
+
+				if (binary) {
+					// Export as GLB
+					const result = await exporter.exportThreeJSGLB(scene, {})
+					if (!(result.data instanceof Uint8Array)) {
+						throw new Error('Expected GLB export to return Uint8Array')
+					}
+					fileSaver.saveAs(
+						new Blob([new Uint8Array(result.data)]),
+						`${baseFileName}.glb`
+					)
+				} else {
+					// Export as GLTF with ZIP
+					const result = await exporter.exportThreeJSGLTF(scene)
+					const zipBuffer = await exporter.createZIPArchive(
+						result,
+						baseFileName
+					)
+					fileSaver.saveAs(
+						new Blob([new Uint8Array(zipBuffer)]),
+						`${baseFileName}.zip`
+					)
+				}
+
+				if (onSaved) onSaved()
+			} catch (error) {
+				console.error('Export failed:', error)
+				if (onError) onError(error as Error)
+			}
+		},
+		[onSaved, onError]
+	)
+
+	const handleDocumentGltfExport = useCallback(
+		async function (
+			jsonDocument: Document,
+			file: ModelFile | null,
+			binary = false,
+			download = true
+		) {
+			try {
+				const exporter = exporterRef.current
+				const baseFileName = file?.name.replace(/\.[^/.]+$/, '') || 'model'
+
+				if (binary) {
+					// Export as GLB
+					const result = await exporter.exportDocumentGLB(jsonDocument)
+					fileSaver.saveAs(
+						new Blob([new Uint8Array(result.data)]),
+						`${baseFileName}.glb`
+					)
+				} else {
+					const result = await exporter.exportDocumentGLTF(jsonDocument)
+
+					if (!download) return result
+
+					// Export as GLTF with ZIP
+					const zipBuffer = await exporter.createZIPArchive(
+						result,
+						baseFileName
+					)
+					fileSaver.saveAs(
+						new Blob([new Uint8Array(zipBuffer)]),
+						`${baseFileName}.zip`
+					)
+				}
+
+				if (onSaved) onSaved()
+			} catch (error) {
+				console.error('Export failed:', error)
+				if (onError) onError(error as Error)
+			}
+		},
+		[onError, onSaved]
+	)
+	return {
+		handleThreeGltfExport,
+		handleDocumentGltfExport
+	}
+}
+
+export default useExportModel

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

@@ -0,0 +1,46 @@
+/* vectreal-core | vctrl/hooks
+Copyright (C) 2024 Moritz Becker
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>. */
+
+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]
+		console.debug(`Event emitted: ${event}`, data)
+		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/index.ts

@@ -0,0 +1,15 @@
+export { default as useLoadModel } from './use-load-model'
+export {
+	type EventHandler,
+	type EventTypes,
+	type InputFileOrDirectory,
+	type LoadData,
+	type ModelFile,
+	type SceneDataLoadOptions,
+	type SceneLoadOptions,
+	type SceneLoadResult,
+	type UseLoadModelReturn,
+	type ServerSceneData
+} from './types'
+export { reconstructGltfFiles } from './utils/reconstruct-files'
+export * from './model-context'

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

@@ -0,0 +1,174 @@
+/* vectreal-core | vctrl/hooks
+Copyright (C) 2024 Moritz Becker
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>. */
+
+import React, { createContext, useContext } from 'react'
+
+import { useOptimizeModel } from '../use-optimize-model'
+import { UseLoadModelReturn } from './types'
+import useLoadModel from './use-load-model'
+
+/**
+ * Props for ModelProvider when an optimizer is provided.
+ * This ensures the optimizer property is required and properly typed.
+ */
+interface ModelProviderPropsWithOptimizer extends React.PropsWithChildren {
+	/** The optimizer instance from useOptimizeModel hook */
+	optimizer: ReturnType<typeof useOptimizeModel>
+}
+
+/**
+ * Props for ModelProvider when no optimizer is used.
+ * The optimizer property must not be provided.
+ */
+interface ModelProviderPropsWithoutOptimizer extends React.PropsWithChildren {
+	/** Explicitly prevents optimizer from being passed */
+	optimizer?: never
+}
+
+/**
+ * Discriminated union of ModelProvider props.
+ * Allows the provider to be used with or without an optimizer,
+ * ensuring type safety for both scenarios.
+ */
+type ModelProviderProps =
+	| ModelProviderPropsWithOptimizer
+	| ModelProviderPropsWithoutOptimizer
+
+/**
+ * Context for model loading with optimizer integration.
+ * When this context has a value, the optimizer property will be fully typed
+ * with all optimization methods and state.
+ */
+const ModelContextWithOptimizer = createContext<
+	UseLoadModelReturn<true> | undefined
+>(undefined)
+
+/**
+ * Context for model loading without optimizer integration.
+ * When this context has a value, the optimizer property will be typed as null.
+ */
+const ModelContextWithoutOptimizer = createContext<
+	UseLoadModelReturn<false> | undefined
+>(undefined)
+
+/**
+ * Provider component for model loading context.
+ *
+ * This component uses a dual-context pattern to provide type-safe access to model loading
+ * functionality with or without optimizer integration.
+ *
+ * @example
+ * // With optimizer
+ * const optimizer = useOptimizeModel()
+ * <ModelProvider optimizer={optimizer}>
+ *   <App />
+ * </ModelProvider>
+ *
+ * @example
+ * // Without optimizer
+ * <ModelProvider>
+ *   <App />
+ * </ModelProvider>
+ *
+ * @param props - Component props
+ * @param props.children - Child components that will have access to the model context
+ * @param props.optimizer - Optional optimizer instance from useOptimizeModel hook
+ */
+const ModelProvider = ({ children, optimizer }: ModelProviderProps) => {
+	// Call the hook once to get the model loading functionality
+	// The generic type will be inferred based on whether optimizer is defined
+	const value = useLoadModel(optimizer)
+
+	// Provide the value to the appropriate context based on whether optimizer is present
+	// This enables type-safe consumption via useModelContext
+	if (optimizer) {
+		// Optimizer is present: use ModelContextWithOptimizer
+		// The type assertion is safe because we know optimizer is defined
+		return (
+			<ModelContextWithOptimizer.Provider
+				value={value as unknown as UseLoadModelReturn<true>}
+			>
+				{children}
+			</ModelContextWithOptimizer.Provider>
+		)
+	}
+
+	// No optimizer: use ModelContextWithoutOptimizer
+	// The type assertion is safe because we know optimizer is undefined
+	return (
+		<ModelContextWithoutOptimizer.Provider
+			value={value as unknown as UseLoadModelReturn<false>}
+		>
+			{children}
+		</ModelContextWithoutOptimizer.Provider>
+	)
+}
+
+/**
+ * Hook to access the model loading context.
+ *
+ * This hook provides type-safe access to model loading functionality.
+ * The return type is automatically inferred based on how the ModelProvider was configured.
+ *
+ * By default (no argument), it assumes an optimizer is present and returns the full
+ * optimizer integration. You can explicitly specify the expected configuration using
+ * the requireOptimizer parameter.
+ *
+ * @example
+ * // Default: assumes optimizer is present
+ * const model = useModelContext()
+ * model.optimizer.applyOptimization() // ✅ Fully typed
+ *
+ * @example
+ * // Explicitly require optimizer
+ * const model = useModelContext(true)
+ * model.optimizer.simplifyOptimization() // ✅ Fully typed
+ *
+ * @example
+ * // Explicitly indicate no optimizer
+ * const model = useModelContext(false)
+ * model.optimizer // ✅ Typed as null
+ *
+ * @throws {Error} If used outside of a ModelProvider
+ * @returns The model loading context with type-safe optimizer property
+ */
+function useModelContext(): UseLoadModelReturn<true>
+/**
+ * @param requireOptimizer - Set to true to explicitly require optimizer integration
+ */
+function useModelContext(requireOptimizer: true): UseLoadModelReturn<true>
+/**
+ * @param requireOptimizer - Set to false to explicitly indicate no optimizer
+ */
+function useModelContext(requireOptimizer: false): UseLoadModelReturn<false>
+ 
+function useModelContext(_?: boolean): UseLoadModelReturn<boolean> {
+	// Check both contexts - only one will have a value based on how ModelProvider was configured
+	const withOptimizer = useContext(ModelContextWithOptimizer)
+	const withoutOptimizer = useContext(ModelContextWithoutOptimizer)
+
+	// Use whichever context has a value (they're mutually exclusive)
+	const context = withOptimizer ?? withoutOptimizer
+
+	// Ensure the hook is used within a ModelProvider
+	if (!context) {
+		throw new Error('useModelContext must be used within a ModelProvider')
+	}
+
+	return context
+}
+
+export { ModelProvider, useModelContext }

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

@@ -0,0 +1,75 @@
+/* vectreal-core | vctrl/hooks
+Copyright (C) 2024 Moritz Becker
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>. */
+
+import { ModelFileTypes } from '@vctrl/core/model-loader'
+
+import { Action, LoadData } from './types'
+
+/**
+ * Initial state for the useReadModelFiles hook
+ *
+ * @property file - Currently loaded file
+ * @property isFileLoading - Flag indicating if a file is currently being loaded
+ * @property progress - Current loading progress (0-100)
+ * @property supportedFileTypes - List of supported file types
+ */
+export const initialState: LoadData = {
+	/**
+	 * Currently loaded file
+	 */
+	file: null,
+	/**
+	 * Flag indicating if a file is currently being loaded
+	 */
+	isFileLoading: false,
+	/**
+	 * Current loading progress (0-100)
+	 */
+	progress: 0,
+	/**
+	 * List of supported file types
+	 * @type {ModelFileTypes[]}
+	 */
+	supportedFileTypes: [
+		ModelFileTypes.gltf,
+		ModelFileTypes.glb,
+		ModelFileTypes.usdz
+	]
+}
+
+/**
+ * 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: LoadData, action: Action): LoadData {
+	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