@vctrl/hooks 0.16.2 → 0.17.0

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

@@ -0,0 +1,19 @@
+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 declare const initialState: LoadData;
+/**
+ * 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
+ */
+declare function reducer(state: LoadData, action: Action): LoadData;
+export default reducer;

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

@@ -0,0 +1,231 @@
+import { ModelFileTypes } from '../../../core/src/model-loader/index.ts';
+import { Object3D } from 'three';
+import { useOptimizeModel } from '../use-optimize-model';
+import { default as eventSystem } from './event-system';
+import { initialState } from './state';
+import { ServerOptions, ServerSceneData } from '../../../core/src/index.ts';
+export type { ExtendedGLTFDocument, SceneAssetDataEntry, SerializedSceneAssetDataMap as SceneAssetDataMap, ServerSceneData, ServerScenePayload } from '../../../core/src/index.ts';
+/**
+ * Type representing the input for file/folder uploads.
+ * Can be either File objects or FileSystemDirectoryHandle for folder drag-and-drop.
+ */
+export type InputFileOrDirectory = (File | FileSystemDirectoryHandle)[];
+/**
+ * Represents a loaded 3D model file with its metadata.
+ */
+export interface ModelFile {
+    /** The Three.js Object3D scene containing the loaded model */
+    model: Object3D;
+    /** The file type/format of the model (GLTF, GLB, USDZ) */
+    type: ModelFileTypes;
+    /** The original filename of the model */
+    name: string;
+    /** Byte size of referenced source package (gltf + referenced buffers/images) */
+    sourcePackageBytes?: number;
+    /** Byte size of referenced texture assets from source package */
+    sourceTextureBytes?: number;
+}
+/**
+ * Configuration options for loading a scene from the server.
+ */
+export interface SceneLoadOptions {
+    /** The unique identifier of the scene to load */
+    sceneId: string;
+    /** Server configuration (endpoint, auth, headers) */
+    serverOptions?: ServerOptions;
+    /** Whether to automatically apply scene settings (default: true) */
+    applySettings?: boolean;
+}
+/**
+ * Configuration options for loading an already-resolved scene payload.
+ */
+export interface SceneDataLoadOptions {
+    /** Optional scene identifier for resolved payloads. */
+    sceneId?: string;
+    /** Resolved server scene payload */
+    sceneData: ServerSceneData;
+    /** Whether to automatically apply scene settings (default: true) */
+    applySettings?: boolean;
+}
+/**
+ * Result of a scene load operation based on server data.
+ * Combines the loaded model with its settings.
+ */
+export interface SceneLoadResult extends ServerSceneData {
+    /** The loaded model file */
+    file: ModelFile;
+    /** Scene ID that was loaded */
+    sceneId?: string;
+}
+/**
+ * State interface for model loading data.
+ * Contains the current loaded file, loading status, and progress information.
+ */
+export interface LoadData {
+    /** The currently loaded model file, or null if no model is loaded */
+    file: ModelFile | null;
+    /** Whether a file is currently being loaded */
+    isFileLoading: boolean;
+    /** Loading progress percentage (0-100) */
+    progress: number;
+    /** List of supported model file types */
+    supportedFileTypes: ModelFileTypes[];
+}
+/**
+ * Action types for the model loading reducer.
+ * Defines all possible state mutations for model loading operations.
+ */
+export type Action = {
+    type: 'set-file';
+    payload: ModelFile;
+} | {
+    type: 'set-file-loading';
+    payload: boolean;
+} | {
+    type: 'set-progress';
+    payload: number;
+} | {
+    type: 'reset-state';
+};
+/**
+ * Available event types emitted by the model loading system.
+ * Used for subscribing to various stages of the loading process.
+ */
+export type EventTypes = 'multiple-models' | 'not-loaded-files' | 'load-start' | 'load-progress' | 'load-complete' | 'load-reset' | 'load-error' | 'server-load-start' | 'server-load-complete' | 'server-load-error';
+/**
+ * Maps event types to their corresponding data payloads.
+ * Ensures type safety when handling events.
+ */
+export type EventData = {
+    /** Array of model files when multiple are detected */
+    'multiple-models': File[];
+    /** Array of unsupported files */
+    'not-loaded-files': File[];
+    /** No data for load start event */
+    'load-start': null;
+    /** Progress value (0-100) */
+    'load-progress': number;
+    /** The loaded model file data */
+    'load-complete': LoadData['file'];
+    /** No data for reset event */
+    'load-reset': null;
+    /** Error object when loading fails */
+    'load-error': Error | unknown;
+    /** Scene ID being loaded from server */
+    'server-load-start': string;
+    /** Complete scene load result */
+    'server-load-complete': SceneLoadResult;
+    /** Error during server scene loading */
+    'server-load-error': Error | unknown;
+};
+/**
+ * Type-safe event handler function.
+ * @template T - The event type being handled
+ */
+export type EventHandler<T extends EventTypes> = (data?: EventData[T]) => void;
+/**
+ * Return type for the useLoadModel hook.
+ * Conditionally includes optimizer integration based on whether an optimizer was provided.
+ *
+ * @template HasOptimizer - Boolean indicating if optimizer integration is included
+ */
+export type UseLoadModelReturn<HasOptimizer extends boolean> = typeof initialState & {
+    /**
+     * Subscribe to model loading events.
+     * @param event - The event type to listen for
+     * @param handler - Callback function to handle the event
+     */
+    on: typeof eventSystem.on;
+    /**
+     * Unsubscribe from model loading events.
+     * @param event - The event type to stop listening for
+     * @param handler - The callback function to remove
+     */
+    off: typeof eventSystem.off;
+    /**
+     * Load 3D model files from File objects or directory handles.
+     * Supports GLTF, GLB, and USDZ formats with associated assets.
+     */
+    load: (filesOrDirectories: InputFileOrDirectory) => Promise<void>;
+    /**
+     * Load a scene from already-resolved scene data.
+     * Preserves original asset payload semantics and bypasses upload-style file processing.
+     */
+    loadFromData: (options: SceneDataLoadOptions) => Promise<SceneLoadResult>;
+    /**
+     * Load a scene from the server by scene ID.
+     * Fetches both the model and scene settings, applies them automatically.
+     *
+     * @param options - Scene loading configuration
+     * @returns Promise resolving to the loaded scene data
+     *
+     * @example
+     * ```tsx
+     * const model = useLoadModel()
+     *
+     * // Load a scene from the server
+     * const scene = await model.loadFromServer({
+     *   sceneId: 'abc-123',
+     *   serverOptions: {
+     *     endpoint: '/api/load-scene',
+     *     apiKey: 'optional-auth-token'
+     *   }
+     * })
+     * ```
+     */
+    loadFromServer: (options: SceneLoadOptions) => Promise<SceneLoadResult>;
+    /**
+     * Reset the model loading state and clear any loaded models.
+     */
+    reset: () => void;
+    /**
+     * Optimizer integration object.
+     * - When optimizer is provided: Contains full optimization methods and state
+     * - When no optimizer: null
+     */
+    optimizer: HasOptimizer extends true ? OptimizerIntegrationReturn<true> : null;
+};
+/**
+ * Return type of the useOptimizeModel hook.
+ * Provides access to all optimization methods and state.
+ */
+export type OptimizerReturnType = ReturnType<typeof useOptimizeModel>;
+/**
+ * Conditional return type for optimizer integration.
+ * Extends the optimizer with additional integration methods when present.
+ *
+ * @template HasOptimizer - Boolean indicating if optimizer is integrated
+ */
+export type OptimizerIntegrationReturn<HasOptimizer extends boolean = false> = HasOptimizer extends true ? OptimizerReturnType & {
+    /**
+     * Whether the optimizer is still preparing the currently visible model.
+     */
+    isPreparing: boolean;
+    /**
+     * Applies an optimization and updates the loaded model with the result.
+     *
+     * This method:
+     * 1. Runs the specified optimization function
+     * 2. Retrieves the optimized model
+     * 3. Loads it back into the scene
+     * 4. Updates the model state
+     *
+     * @template TOptions - Type of options for the optimization function
+     * @param optimizationFunction - The optimization to apply (e.g., simplifyOptimization)
+     * @param options - Configuration options for the optimization
+     * @returns Promise that resolves when optimization is complete and model is updated
+     *
+     * @example
+     * // Apply simplification optimization
+     * await optimizer.applyOptimization(
+     *   optimizer.simplifyOptimization,
+     *   { ratio: 0.5 }
+     * )
+     *
+     * @example
+     * // Apply multiple optimizations in sequence
+     * await optimizer.applyOptimization(optimizer.dedupOptimization)
+     * await optimizer.applyOptimization(optimizer.quantizeOptimization, { bits: 12 })
+     */
+    applyOptimization: <TOptions>(optimizationFunction?: ((options?: TOptions) => Promise<void>) | undefined, options?: TOptions) => Promise<void>;
+} : null;

package/use-load-model/use-load-model.d.ts

@@ -0,0 +1,30 @@
+import { UseLoadModelReturn } from './types';
+import { useOptimizeModel } from '../use-optimize-model';
+/**
+ * Custom hook to load and manage 3D models with optional optimization integration.
+ *
+ * This hook provides a complete solution for loading 3D models (GLTF, GLB, USDZ) with
+ * optional integration of model optimization capabilities. The return type is conditionally
+ * typed based on whether an optimizer is provided.
+ *
+ * **Type Safety:**
+ * - When called with an optimizer: `optimizer` property is fully typed with optimization methods
+ * - When called without an optimizer: `optimizer` property is typed as `null`
+ *
+ * @example
+ * // With optimizer integration
+ * const optimizer = useOptimizeModel()
+ * const model = useLoadModel(optimizer)
+ * model.optimizer.applyOptimization() // ✅ Fully typed
+ *
+ * @example
+ * // Without optimizer
+ * const model = useLoadModel()
+ * model.optimizer // ✅ Typed as null
+ *
+ * @template T - The type of the optimizer parameter (inferred automatically)
+ * @param optimizer - Optional optimizer hook returned from useOptimizeModel
+ * @returns Model loading state and methods, with conditionally typed optimizer property
+ */
+declare function useLoadModel<T extends ReturnType<typeof useOptimizeModel> | undefined>(optimizer?: T): UseLoadModelReturn<T extends undefined ? false : true>;
+export default useLoadModel;

package/use-load-model/utils/calculate-referenced-bytes.d.ts

@@ -0,0 +1,8 @@
+import { ServerSceneData } from '../types';
+type ReferencedBytes = {
+    sourcePackageBytes: number;
+    textureBytes: number;
+};
+export declare function calculateReferencedBytesFromFiles(gltfFile: File, assetFiles: File[]): Promise<ReferencedBytes>;
+export declare function calculateReferencedBytesFromServerScene(data: ServerSceneData): ReferencedBytes;
+export {};

package/use-load-model/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { default as readDirectory } from './read-directory';
+export { reconstructGltfFiles } from './reconstruct-files';
+export { calculateReferencedBytesFromFiles, calculateReferencedBytesFromServerScene } from './calculate-referenced-bytes';
+export { resolveServerSceneDataContract } from './resolve-scene-payload';

package/use-load-model/utils/read-directory.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Recursively reads a directory
+ *
+ * @param directoryHandle - The directory handle to read
+ * @returns - An array of file objects
+ */
+declare function readDirectory(directoryHandle: FileSystemDirectoryHandle): Promise<File[]>;
+export default readDirectory;

package/use-load-model/utils/reconstruct-files.d.ts

@@ -0,0 +1,29 @@
+import { InputFileOrDirectory, ServerSceneData } from '../types';
+/**
+ * Reconstructs GLTF and asset files from scene data received from the server.
+ *
+ * This function converts the server's scene data format (GLTF JSON + binary assets)
+ * back into File objects that can be loaded by the model loader. This is the reverse
+ * operation of what happens when a scene is saved to the server.
+ *
+ * The function:
+ * 1. Converts binary asset data (stored as number arrays) back into File objects
+ * 2. Creates a GLTF file from the JSON structure
+ * 3. Returns an array of files compatible with the model loading system
+ *
+ * @param data - Scene data from the server containing GLTF JSON and assets
+ * @returns Array of File objects ready to be loaded (GLTF file + asset files)
+ *
+ * @example
+ * ```typescript
+ * // Load scene data from server
+ * const sceneData = await ServerCommunicationService.loadScene('scene-123')
+ *
+ * // Reconstruct files
+ * const files = reconstructGltfFiles(sceneData)
+ *
+ * // Load into the viewer
+ * await modelLoader.load(files)
+ * ```
+ */
+export declare function reconstructGltfFiles(data: ServerSceneData): InputFileOrDirectory;

package/use-load-model/utils/resolve-scene-payload.d.ts

@@ -0,0 +1,6 @@
+import { ServerSceneData, ServerScenePayload } from '../../../../core/src/index.ts';
+/**
+ * Resolves raw scene payload from the API into normalized scene data used by hooks.
+ * This keeps payload-shape adaptation in one explicit contract boundary.
+ */
+export declare function resolveServerSceneDataContract(payload: ServerScenePayload): ServerSceneData;