@liveroom-tech/react-immersive 4.3.0 → 5.0.0

package/dist/ModelViewer-DOexHkJC.d.ts

@@ -0,0 +1,448 @@
+import { ReactNode } from 'react';
+import { g as ObjectBinding, a1 as ViewerCameraState, y as SceneAnnotationMarker, f as ObjectActionEvent, a2 as ViewerObjectInfo, w as ObjectPointerEvent, a0 as ViewerCameraConfig, J as SceneConfig } from './objectCatalog-5W8n5xNQ.js';
+import { M as ModelFormat, a as ViewerModelInfo } from './modelInfo-CEmmvVCH.js';
+import { CameraControls } from '@react-three/drei';
+import { Object3D } from 'three';
+
+type CameraLimits = {
+    /** Closest the camera can get to its target, in scene units. Default 0. */
+    minDistance?: number;
+    /** Farthest the camera can get from its target, in scene units. Default Infinity. */
+    maxDistance?: number;
+    /**
+     * Lowest vertical angle, in degrees: 0 looks straight down from above, 90 is
+     * level with the target, 180 looks straight up from below. Default 0.
+     */
+    minPolarAngle?: number;
+    /** Highest vertical angle, in degrees (see minPolarAngle). Default 180. */
+    maxPolarAngle?: number;
+    /**
+     * Leftmost horizontal angle, in degrees around the vertical axis: 0 views
+     * the target from the front (+Z), 90 from its right (+X), -90 from its
+     * left. Default -Infinity (no limit).
+     */
+    minAzimuthAngle?: number;
+    /** Rightmost horizontal angle, in degrees (see minAzimuthAngle). Default Infinity. */
+    maxAzimuthAngle?: number;
+    /** An axis-aligned world-space box the camera's target can pan within. */
+    panBoundary?: [min: [number, number, number], max: [number, number, number]];
+    /** Keeps the camera itself, not just its target, inside panBoundary. Default false. */
+    boundaryEnclosesCamera?: boolean;
+    /** How strongly panning slows near panBoundary, 0–1. Default 0. */
+    boundaryFriction?: number;
+};
+
+type MouseControllerPosition = 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'center' | 'center-bottom' | 'center-top';
+
+type PerformanceProfile = "auto" | "high" | "low";
+
+type XRScaleMode = "normalized" | "real-world";
+
+/** A starting set of ModelViewer props for a common kind of page. */
+type ModelViewerPreset = "minimal" | "showcase" | "configurator" | "inspector";
+type ModelViewerUiOptions = {
+    /** The left panel for the selected object. Default `true`. */
+    objectPanel?: boolean;
+    /** The right panel listing the model's objects. Default `true`. */
+    sceneObjects?: boolean;
+    /** The download button; a string also sets the file name. Default `true`. */
+    download?: boolean | string;
+    /** The reset-view button. Default `true`. */
+    reset?: boolean;
+    /** The loading overlay and load-error message. Default `true`. */
+    loadingOverlay?: boolean;
+    /** The axis gizmo in the top-right corner. Default `false`. */
+    viewGizmo?: boolean;
+    /** The on-screen movement pad; an object also places it. Default `false`. */
+    mouseController?: boolean | {
+        position?: MouseControllerPosition;
+        opacity?: number;
+    };
+    /** Previous/Stop/Next controls for annotation tours. Default `true`. */
+    annotationNavigation?: boolean;
+    /** Show an annotation's details when its marker is hovered. Default `false`. */
+    annotationOnHover?: boolean;
+    /** Highlight objects under the pointer. Default `true`. */
+    highlightOnHover?: boolean;
+};
+/**
+ * Takes over parts of texture positioning (`texturePositioning`). Fields left
+ * out keep the viewer's own behavior, which reads and writes the binding.
+ */
+type TexturePositioningControls = {
+    /** Shown in the Offset fields instead of the binding's offset. */
+    offset?: [number, number];
+    /** Shown in the Rotation field instead of the binding's, in degrees (0–360). */
+    rotationDegrees?: number;
+    /** Replaces the viewer's write when an Offset field changes. */
+    onOffsetChange?: (objectId: string, axisIndex: 0 | 1, value: number) => void;
+    /** Replaces the viewer's write when the Rotation field changes. */
+    onRotationChange?: (objectId: string, degrees: number) => void;
+    /** Whether to show "Done positioning" rather than the hint. */
+    isPositioning?: boolean;
+    /** Called after "Done positioning" ends Move/Zoom mode. */
+    onEndPositioning?: () => void;
+};
+type ModelViewerToolsOptions = {
+    /** Distance and dimension tools; an object also sets the unit. Default `false`. */
+    measure?: boolean | {
+        unit?: string;
+    };
+    /** The UV checker toggle. Default `false`. */
+    uvChecker?: boolean;
+    /** The exploded-view slider. Default `false`. */
+    explode?: boolean;
+    /** Texture offset, rotation and Move/Zoom for textured objects. Default `false`. */
+    texturePositioning?: boolean | TexturePositioningControls;
+};
+type ModelViewerControlsOptions = {
+    /** Orbit, pan and zoom with the pointer. Default `true`. */
+    enabled?: boolean;
+    /** Move the camera with the keyboard while the canvas has focus. Default `false`. */
+    keyboard?: boolean;
+    /** Allow zooming. Default `true`. */
+    zoom?: boolean;
+    /** Zoom to an object when it's selected. Default `true`. */
+    zoomOnSelect?: boolean;
+    /** Turn the model slowly; a number sets the speed (1 is normal). Default `false`. */
+    autoRotate?: boolean | number;
+    /** Re-frame the model when the viewer is resized. Default `true`. */
+    refitOnResize?: boolean;
+    /** Distance, angle and pan limits for the camera. */
+    limits?: CameraLimits;
+    /** Movement pad speed. Default `0.08`. */
+    moveSensitivity?: number;
+    /** Movement pad zoom speed. Default `1`. */
+    zoomSensitivity?: number;
+};
+type ModelViewerPerfOptions = {
+    /** `"demand"` draws only when something changes. Default `"demand"`. */
+    renderMode?: "always" | "demand";
+    /** Highest device pixel ratio to render at. Default `2`. */
+    maxDpr?: number;
+    /** `"low"` trades quality for speed on weak devices. Default `"auto"`. */
+    profile?: PerformanceProfile;
+    /** Needed for Download PNG and captureImage; costs GPU time. Default `false`. */
+    preserveDrawingBuffer?: boolean;
+};
+type ModelViewerTilesOptions = {
+    /** A 3D Tiles `tileset.json` to stream instead of loading `modelUrl` whole. */
+    url?: string | null;
+    /** Screen-space error target; lower is sharper. Default `8`. */
+    errorTarget?: number;
+    /** Most parsed tiles kept in memory. Default `800`. */
+    cacheSize?: number;
+};
+type ModelViewerXrOptions = {
+    /** "View in your space" (AR) and "Enter VR". Default `false`. */
+    enabled?: boolean;
+    /** A USDZ file for iOS AR Quick Look. */
+    usdzUrl?: string;
+    /** How the model is sized in AR. Default `"normalized"`. */
+    scaleMode?: XRScaleMode;
+    /** The page the desktop QR code opens on a phone. Default: the current page. */
+    mobileHandoffUrl?: string;
+};
+type ModelViewerDecoderOptions = {
+    /** Directory of the DRACO decoder files, or `false`. */
+    draco?: string | false;
+    /** Directory of the Basis/KTX2 transcoder files, or `false`. */
+    ktx2?: string | false;
+    /** Enable the bundled Meshopt decoder. Default `true`. */
+    meshopt?: boolean;
+};
+type GroupedModelViewerProps = {
+    /**
+     * A starting set of props for a common kind of page. Anything else you pass
+     * overrides it.
+     */
+    preset?: ModelViewerPreset;
+    ui?: ModelViewerUiOptions;
+    tools?: ModelViewerToolsOptions;
+    controls?: ModelViewerControlsOptions;
+    perf?: ModelViewerPerfOptions;
+    tiles?: ModelViewerTilesOptions;
+    xr?: ModelViewerXrOptions;
+    decoders?: ModelViewerDecoderOptions;
+};
+/** What each preset sets. Props that aren't listed keep their defaults. */
+declare const MODEL_VIEWER_PRESETS: Readonly<Record<ModelViewerPreset, Readonly<Partial<ModelViewerProps>>>>;
+
+type CameraControllerType = "orbit" | "pointerLock";
+
+type CinematicWaypoint = {
+    position: [number, number, number];
+    target: [number, number, number];
+    /**
+     * Orbit angles in radians, as BindingBuilder captures them: position and
+     * target alone can't represent the rotation straight above or below the
+     * target. Leave them out when writing waypoints by hand.
+     */
+    azimuthAngle?: number;
+    polarAngle?: number;
+    segmentDuration?: number;
+};
+type CinematicConfig = {
+    waypoints?: CinematicWaypoint[];
+    duration?: number;
+    loop?: boolean;
+    autoPlay?: boolean;
+};
+
+type CaptureImageOptions = {
+    width?: number;
+    height?: number;
+    transparent?: boolean;
+};
+
+type ViewerCameraPreset = {
+    position: [number, number, number];
+    target: [number, number, number];
+    fov?: number | null;
+    zoom?: number;
+    azimuthAngle?: number;
+    polarAngle?: number;
+};
+type UseViewerCameraOptions = {
+    /** Camera position applied once when each model becomes ready. */
+    initialPosition?: [number, number, number];
+    /** Orbit target applied once when each model becomes ready. */
+    initialTarget?: [number, number, number];
+    /** Whether the initial position/target should animate. Defaults to false. */
+    initialTransition?: boolean;
+    /** Named views that can be opened with goToPreset. */
+    presets?: Record<string, ViewerCameraPreset>;
+};
+type HomeCameraState = {
+    position: [number, number, number];
+    target: [number, number, number];
+};
+type ViewerReadyState = {
+    objectBindings: Record<string, ObjectBinding>;
+    homeCameraState: HomeCameraState | null;
+    captureImage: (options?: CaptureImageOptions) => Promise<string>;
+    invalidate: () => void;
+    /**
+     * The live three.js scene, camera-controls instance, and model nodes, for
+     * integrations the rest of the API doesn't cover. Their shapes are those
+     * libraries' own and can change with them.
+     */
+    raw: {
+        controls: CameraControls;
+        scene: Object3D | null;
+        /** Model nodes by binding key and node name. */
+        nodes: Record<string, Object3D>;
+    };
+};
+type ViewerCameraProps = {
+    cameraState: ViewerCameraState | null;
+    cameraPresets: Record<string, ViewerCameraPreset>;
+    resetView: () => Promise<boolean>;
+    focusObject: (objectId: string) => Promise<boolean>;
+    fitScene: () => Promise<boolean>;
+    setCameraTarget: (target: [number, number, number], enableTransition?: boolean) => Promise<boolean>;
+    setCameraState: (state: ViewerCameraState, enableTransition?: boolean) => Promise<boolean>;
+    lookAt: (position: [number, number, number], target: [number, number, number], enableTransition?: boolean) => Promise<boolean>;
+    /**
+     * Orbits the camera around its target to the given angles, in degrees.
+     * Azimuth is the horizontal angle (0 is the front, +Z; 90 the right, +X);
+     * polar is the vertical angle (0 straight down, 90 level, 180 straight up).
+     */
+    orbitTo: (azimuthDegrees: number, polarDegrees: number, enableTransition?: boolean) => Promise<boolean>;
+    dollyTo: (distance: number, enableTransition?: boolean) => Promise<boolean>;
+    savePreset: (name: string) => ViewerCameraState | null;
+    goToPreset: (name: string, enableTransition?: boolean) => Promise<boolean>;
+    handleCameraChange: (state: ViewerCameraState) => void;
+    handleViewerReady: (viewer: ViewerReadyState) => void;
+};
+declare function useViewerCamera(options?: UseViewerCameraOptions): ViewerCameraProps;
+
+type AnimationClipInfo = {
+    sourceName: string;
+    duration: number;
+};
+type AnimationPlaybackState = {
+    currentClip: string | null;
+    isPlaying: boolean;
+    speed: number;
+    time: number;
+    duration: number;
+};
+type AnimationControls = {
+    clips: string[];
+    clipDetails?: AnimationClipInfo[];
+    play: (clipName: string) => void;
+    pause: () => void;
+    stop: () => void;
+    setSpeed: (speed: number) => void;
+    seek?: (time: number) => void;
+    getState?: () => AnimationPlaybackState;
+    subscribe?: (listener: (state: AnimationPlaybackState) => void) => () => void;
+};
+type ViewerAnimationsProps = {
+    clips: string[];
+    clipDetails: AnimationClipInfo[];
+    currentClip: string | null;
+    isPlaying: boolean;
+    speed: number;
+    time: number;
+    duration: number;
+    play: (clipName: string) => void;
+    pause: () => void;
+    stop: () => void;
+    setSpeed: (speed: number) => void;
+    seek: (time: number) => void;
+    handleAnimationsReady: (controls: AnimationControls) => void;
+};
+declare function useViewerAnimations(): ViewerAnimationsProps;
+
+type ObjectTransformSpace = "local" | "world";
+
+type AnnotationMarker = SceneAnnotationMarker & {
+    markerId?: string;
+};
+type CustomObjectBindingDataPanelProps = {
+    isOpen: boolean;
+    selectedObject: ObjectBinding | null;
+    currentAction: ObjectActionEvent | null;
+    onClose: () => void;
+    onAction: (event: ObjectActionEvent) => void;
+};
+type CustomSceneObjectsPanelProps = {
+    objectBindings: Record<string, ObjectBinding>;
+    onAction?: (event: ObjectActionEvent) => void;
+    onFocus?: (binding: ObjectBinding) => void;
+    onHover?: (binding: ObjectBinding | null) => void;
+};
+type ModelViewerProps = GroupedModelViewerProps & {
+    modelUrl: string;
+    /** Optional 3D Tiles manifest used instead of loading `modelUrl` monolithically. */
+    tilesetUrl?: string | null;
+    /** Screen-space error target for streamed 3D Tiles. Lower is sharper. */
+    tilesErrorTarget?: number;
+    /** Maximum number of parsed tiles retained by the client cache. */
+    tilesCacheSize?: number;
+    /**
+     * Every bindable object in the model: each named mesh, under the identifier
+     * bindings are keyed by. Reported each time a model loads; for a streamed
+     * model it comes from the catalog beside `tileset.json`, before the tiles
+     * that contain those objects have necessarily loaded.
+     */
+    onObjectCatalog?: (objects: ViewerObjectInfo[]) => void;
+    /** Explicit format for extensionless or signed model URLs. */
+    modelFormat?: ModelFormat;
+    licenseKey: string;
+    /**
+     * The model's interactive objects, keyed by node name. Defaults to `"auto"`:
+     * a default binding for every mesh, generated when the model loads and
+     * reported through `onObjectBindingsChange`.
+     */
+    objectBindings?: Record<string, ObjectBinding> | "auto";
+    selectedObject?: ObjectBinding | null;
+    panelHoveredObject?: ObjectBinding | null;
+    onObjectBindingsChange?: (next: Record<string, ObjectBinding>) => void;
+    onObjectSelect?: (binding: ObjectBinding | null) => void;
+    onObjectHover?: (binding: ObjectBinding | null) => void;
+    /**
+     * An object was double-clicked. Return `true` to skip the viewer's own
+     * double-click behavior: moving the orbit point to that spot, or starting
+     * texture positioning when that's enabled.
+     */
+    onObjectDoubleClick?: (event: ObjectPointerEvent) => boolean | void;
+    /**
+     * An object was right-clicked or, on touch screens, long-pressed. Use it to
+     * open your own menu at `clientX`/`clientY`. A right-drag still pans.
+     */
+    onObjectContextMenu?: (event: ObjectPointerEvent) => void;
+    /** The model finished loading: its bounds and mesh count. */
+    onModelLoaded?: (model: ViewerModelInfo) => void;
+    onLoadError?: (error: unknown) => void;
+    onProgress?: (event: ProgressEvent) => void;
+    onCameraControllerChange?: (controller: CameraControllerType) => void;
+    cameraControllerType?: CameraControllerType;
+    onAction?: (event: ObjectActionEvent) => void;
+    onHiddenObjectsChange?: (next: Record<string, boolean>) => void;
+    /** The camera moved. Fires often while the user orbits, pans or zooms. */
+    onCameraChange?: (state: ViewerCameraState) => void;
+    onViewerReady?: (viewer: ViewerReadyState) => void;
+    onTextureUpload?: (file: File, objectId: string) => Promise<string>;
+    onAnimationsReady?: (controls: AnimationControls) => void;
+    onAnnotationsChange?: (annotations: AnnotationMarker[]) => void;
+    activeAnnotation?: AnnotationMarker | null;
+    onActiveAnnotationChange?: (annotation: AnnotationMarker | null) => void;
+    camera?: ViewerCameraConfig;
+    cameraLimits?: CameraLimits;
+    backgroundColor?: string;
+    shadows?: boolean;
+    showObjectBindingDataPanel?: boolean;
+    customObjectBindingDataPanel?: (props: CustomObjectBindingDataPanelProps) => ReactNode;
+    customSceneObjectsPanel?: (props: CustomSceneObjectsPanelProps) => ReactNode;
+    showSceneObjectsPanel?: boolean;
+    showDownloadButton?: boolean;
+    downloadFilename?: string;
+    showResetButton?: boolean;
+    showLoadingOverlay?: boolean;
+    showMouseController?: boolean;
+    mouseControllerPosition?: MouseControllerPosition;
+    mouseControllerOpacity?: number;
+    moveSensitivity?: number;
+    zoomSensitivity?: number;
+    sceneConfig?: SceneConfig;
+    disableZoom?: boolean;
+    zoomOnSelected?: boolean;
+    highlightOnHover?: boolean;
+    onAutoFit?: () => Promise<boolean>;
+    enableCameraControls?: boolean;
+    moveModeEnabled?: boolean;
+    /** Aligns PivotControls to the scene or to the selected object. */
+    objectTransformSpace?: ObjectTransformSpace;
+    /** Enables canvas-focused camera shortcuts. Disabled by default. */
+    enableKeyboardNavigation?: boolean;
+    refitOnResize?: boolean;
+    renderMode?: "always" | "demand";
+    maxDpr?: number;
+    preserveDrawingBuffer?: boolean;
+    performanceProfile?: PerformanceProfile;
+    dracoDecoderPath?: string | false;
+    ktx2TranscoderPath?: string | false;
+    meshopt?: boolean;
+    showMeasureTools?: boolean;
+    showUvCheckerButton?: boolean;
+    showExplodeControls?: boolean;
+    cinematic?: boolean | CinematicConfig;
+    measurementUnit?: string;
+    enableXR?: boolean;
+    usdzUrl?: string;
+    arScaleMode?: XRScaleMode;
+    mobileHandoffUrl?: string;
+    showAnnotationNavigation?: boolean;
+    showAnnotationOnHover?: boolean;
+    onSceneConfigChange?: (config: SceneConfig) => void;
+    showViewGizmo?: boolean;
+    /**
+     * Your own UI over the 3D view: badges, HUDs, custom panels. It sits above
+     * the model and below the viewer's toolbars. The layer lets pointer events
+     * through to the model; its direct children receive them, so position them
+     * yourself (for example `position: "absolute"`).
+     */
+    overlay?: ReactNode;
+    /**
+     * react-three-fiber elements rendered inside the scene, for anything the
+     * viewer can't do itself. They work with three.js directly, so they're
+     * outside the viewer's own API and can break when three.js or
+     * react-three-fiber change.
+     */
+    unsafe_sceneChildren?: ReactNode;
+    autoRotate?: boolean;
+    autoRotateSpeed?: number;
+    /**
+     * Texture positioning for objects with an uploaded texture: Offset and
+     * Rotation fields in the Change Material panel, and Move/Zoom mode on
+     * double-click (drag to move, scroll to scale). Off by default. Pass `true`,
+     * or an object to take over parts of it; changes are written to the
+     * binding's `style.material.texture`.
+     */
+    texturePositioning?: boolean | TexturePositioningControls;
+};
+
+export { type AnimationClipInfo as A, type CameraControllerType as C, type GroupedModelViewerProps as G, type HomeCameraState as H, MODEL_VIEWER_PRESETS as M, type ObjectTransformSpace as O, type PerformanceProfile as P, type TexturePositioningControls as T, type UseViewerCameraOptions as U, type ViewerAnimationsProps as V, type XRScaleMode as X, type AnimationControls as a, type AnimationPlaybackState as b, type AnnotationMarker as c, type CameraLimits as d, type CaptureImageOptions as e, type CinematicConfig as f, type CinematicWaypoint as g, type CustomObjectBindingDataPanelProps as h, type CustomSceneObjectsPanelProps as i, type ModelViewerControlsOptions as j, type ModelViewerDecoderOptions as k, type ModelViewerPerfOptions as l, type ModelViewerPreset as m, type ModelViewerProps as n, type ModelViewerTilesOptions as o, type ModelViewerToolsOptions as p, type ModelViewerUiOptions as q, type ModelViewerXrOptions as r, type MouseControllerPosition as s, type ViewerCameraPreset as t, type ViewerCameraProps as u, type ViewerReadyState as v, useViewerAnimations as w, useViewerCamera as x };