@liveroom-tech/react-immersive 5.0.2 → 5.1.0

package/dist/{objectCatalog-5W8n5xNQ.d.mts → objectCatalog-BIeXURoq.d.ts}

@@ -104,6 +104,11 @@ type SceneModelConfig = {
     shading: "lit" | "unlit" | "normals";
     autoRotate?: boolean;
     autoRotateSpeed?: number;
+    /**
+     * The glTF material variant (KHR_materials_variants) to show, by name, or
+     * null for the model's default materials.
+     */
+    materialVariant?: string | null;
 };
 type SceneCameraConfig = {
     fieldOfView: number;
@@ -149,7 +154,7 @@ type SceneGroundShadowConfig = {
     height: number;
     size: number;
 };
-declare const ANIMATION_LOOP_MODES: readonly ["repeat", "once"];
+declare const ANIMATION_LOOP_MODES: readonly ["repeat", "once", "ping-pong"];
 type AnimationLoopMode = (typeof ANIMATION_LOOP_MODES)[number];
 type SceneAnimationClipConfig = {
     sourceName: string;
@@ -384,6 +389,73 @@ type SceneCinematicConfig = {
     loop: boolean;
     autoPlay: boolean;
 };
+declare const SECTION_AXES: readonly ["x", "y", "z"];
+type SceneSectionAxis = (typeof SECTION_AXES)[number];
+type SceneSectionConfig = {
+    enabled: boolean;
+    /** The world axis the cut runs across; `"y"` gives a floor-plan cut. */
+    axis: SceneSectionAxis;
+    /**
+     * Where the cut is along the axis, as a share of the model's size: 0 at
+     * its minimum, 1 at its maximum.
+     */
+    position: number;
+    /**
+     * Keep the part above the cut (the higher side along the axis) instead of
+     * the part below it.
+     */
+    flip: boolean;
+};
+declare const DEFAULT_SECTION_CONFIG: SceneSectionConfig;
+/**
+ * What an object's data must look like for a rule to apply to it. A list
+ * applies when every condition in it matches.
+ */
+type SceneStyleCondition = {
+    /** A key of `binding.metrics`. */
+    metric: string;
+    /** Applies when the value is greater than this. */
+    above?: number;
+    /** Applies when the value is less than this. */
+    below?: number;
+} | {
+    status: ObjectBindingStatus | ObjectBindingStatus[];
+} | {
+    /** A key of `binding.metadata`; dots reach into nested objects. */
+    metadata: string;
+    equals: string | number | boolean | null;
+};
+type SceneStyleColorScale = {
+    /** A key of `binding.metrics`. */
+    metric: string;
+    /**
+     * `[value, "#rrggbb"]` pairs. Values between two stops blend their colours;
+     * values outside the stops take the nearest one.
+     */
+    stops: [number, string][];
+    /** The material colour it sets. Default `"baseColor"`. */
+    channel?: "baseColor" | "emissive";
+};
+type SceneStylePulse = {
+    /** The glow colour at the pulse's peak. Default `"#ff3b30"`. */
+    color?: string;
+    /** Pulses per second. Default `1`. */
+    speed?: number;
+};
+type SceneStyleRule = {
+    id: string;
+    label?: string;
+    /** The objects the rule considers; every bound object when left out. */
+    target?: ObjectBindingTarget;
+    /** When the rule applies; always, when left out. */
+    when?: SceneStyleCondition | SceneStyleCondition[];
+    /** Material overrides, over the object's own `style.material`. */
+    material?: ObjectBindingMaterial;
+    /** A colour taken from a metric's value. */
+    colorScale?: SceneStyleColorScale;
+    /** A glow that fades in and out, to draw attention. */
+    pulse?: boolean | SceneStylePulse;
+};
 type SceneConfig = {
     model: SceneModelConfig;
     camera: SceneCameraConfig;
@@ -397,6 +469,13 @@ type SceneConfig = {
     animations: SceneAnimationConfig;
     annotations: SceneAnnotationMarker[];
     cinematic?: SceneCinematicConfig;
+    /**
+     * Data-driven looks for bound objects, applied in order, so a later rule
+     * wins over an earlier one where both set something.
+     */
+    styleRules?: SceneStyleRule[];
+    /** A cut-away view across the model. Off when left out. */
+    section?: SceneSectionConfig;
 };
 declare const DEFAULT_SCENE_CONFIG: SceneConfig;
 
@@ -407,6 +486,146 @@ type SceneConfigPatch = DeepPartial<SceneConfig>;
  */
 declare function patchSceneConfig(sceneConfig: SceneConfig, patch: SceneConfigPatch): SceneConfig;
 
+type AnimationClipInfo = {
+    sourceName: string;
+    duration: number;
+};
+/** How `play` starts a clip. */
+type AnimationPlayOptions = {
+    /**
+     * Keep the clips already playing, instead of stopping them, so several
+     * clips run at once (a left and a right door, say). Default `false`.
+     */
+    alongside?: boolean;
+    /**
+     * Seconds to fade the clip in, and to fade out the clips it replaces, for a
+     * smooth blend between them. Default `0`.
+     */
+    fade?: number;
+    /**
+     * Play backwards, from wherever the clip is, or from its end. Plays a
+     * "door opens" clip as the door closing. Default `false`.
+     */
+    reverse?: boolean;
+};
+/**
+ * `"finished"`: a play-once clip that reached its end and holds its last pose
+ * until it's stopped or played again.
+ */
+type AnimationClipStatus = "playing" | "paused" | "finished";
+/** One clip that is playing, paused, or holding its finished pose. */
+type AnimationClipState = {
+    clip: string;
+    status: AnimationClipStatus;
+    /** Position in the clip, in seconds. */
+    time: number;
+    /** Length of the clip, in seconds. */
+    duration: number;
+    speed: number;
+    reverse: boolean;
+};
+type AnimationPlaybackState = {
+    /** The clip played most recently, while it's active. */
+    currentClip: string | null;
+    /** Whether any clip is playing. */
+    isPlaying: boolean;
+    speed: number;
+    time: number;
+    duration: number;
+    /** Every active clip, most recently played last. */
+    active: AnimationClipState[];
+};
+/**
+ * Leave out `clip` to act on every active clip; pass one to act on that clip
+ * alone.
+ */
+type AnimationControls = {
+    clips: string[];
+    clipDetails?: AnimationClipInfo[];
+    play: (clipName: string, options?: AnimationPlayOptions) => void;
+    pause: (clipName?: string) => void;
+    /** Stops and resets the pose. */
+    stop: (clipName?: string) => void;
+    /** Without a clip, also the speed of clips played later without their own. */
+    setSpeed: (speed: number, clipName?: string) => void;
+    seek?: (time: number, clipName?: string) => 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;
+    /** Every active clip, most recently played last. */
+    active: AnimationClipState[];
+    play: (clipName: string, options?: AnimationPlayOptions) => void;
+    pause: (clipName?: string) => void;
+    stop: (clipName?: string) => void;
+    setSpeed: (speed: number, clipName?: string) => void;
+    seek: (time: number, clipName?: string) => void;
+    handleAnimationsReady: (controls: AnimationControls) => void;
+};
+declare function useViewerAnimations(): ViewerAnimationsProps;
+
+/** A glow cycling on one object, from its style rules. */
+type StyledObjectPulse = {
+    color: string;
+    /** Pulses per second. */
+    speed: number;
+};
+type StyledObjectBindings = {
+    /**
+     * The bindings as the rules style them. A binding no rule changed is the
+     * same object as the one passed in.
+     */
+    bindings: Record<string, ObjectBinding>;
+    /** Pulsing objects, by binding key. */
+    pulses: Record<string, StyledObjectPulse>;
+    /** The binding a styled one came from (itself when no rule changed it). */
+    sourceOf: (binding: ObjectBinding) => ObjectBinding;
+};
+/**
+ * The colour a colour scale gives a value: a blend of the two stops around it,
+ * or the nearest stop outside them. Null when there's no usable stop.
+ */
+declare function colorScaleValue(stops: SceneStyleColorScale["stops"], value: number): string | null;
+/**
+ * Styles bindings with scene style rules, for rendering. Rules apply in order
+ * over each object's own `style.material`, so a later rule wins where two set
+ * the same thing. The bindings passed in are never changed.
+ */
+declare function applyStyleRules(bindings: Record<string, ObjectBinding>, rules: readonly SceneStyleRule[] | undefined): StyledObjectBindings;
+
+/**
+ * Objects to focus on. Everything else is ghosted (drawn faintly) or hidden
+ * until the isolation is cleared, without changing any binding.
+ */
+type ViewerIsolation = {
+    /** The objects that stay: an id, a list of ids, `{ group }`, `{ tag }`, or `{ type }`. */
+    target: ObjectBindingTarget;
+    /** What happens to everything else. Default `"ghost"`. */
+    mode?: "ghost" | "hide";
+    /** How visible ghosted objects are, 0–1. Default `0.12`. */
+    ghostOpacity?: number;
+};
+type IsolatedObjectBindings = StyledObjectBindings & {
+    /** Binding keys that are ghosted or hidden. Pointer picking ignores them. */
+    setAside: Set<string>;
+};
+/** The binding keys an isolation keeps; empty when it keeps nothing. */
+declare function isolatedBindingKeys(bindings: Record<string, ObjectBinding>, isolation: ViewerIsolation | null | undefined): Set<string>;
+/**
+ * Ghosts or hides every object an isolation doesn't keep, for rendering. The
+ * bindings passed in are never changed. An isolation that keeps nothing (a
+ * target matching no object) changes nothing either, rather than fading out
+ * the whole model.
+ */
+declare function applyIsolation(styled: StyledObjectBindings, isolation: ViewerIsolation | null | undefined): IsolatedObjectBindings;
+
 type ObjectBindingsActionEffect = {
     target: ObjectBindingTarget;
     objectBindings: ObjectBindingPatch;
@@ -437,24 +656,36 @@ type CameraAction = {
 type CameraActionEffect = {
     camera: CameraAction;
 };
-type AnimationAction = {
+/**
+ * `play` replaces the clips already playing unless `alongside` is set. The
+ * others act on `clip`, or on every active clip when it's left out.
+ */
+type AnimationAction = ({
     type: "play";
     clip: string;
-} | {
+} & AnimationPlayOptions) | {
     type: "pause";
+    clip?: string;
 } | {
     type: "stop";
+    clip?: string;
 } | {
     type: "set-speed";
     speed: number;
+    clip?: string;
 } | {
     type: "seek";
     time: number;
+    clip?: string;
 };
 type AnimationActionEffect = {
     animation: AnimationAction;
 };
-type ObjectActionEffect = ObjectBindingsActionEffect | SceneConfigActionEffect | VisibilityActionEffect | CameraActionEffect | AnimationActionEffect;
+/** Isolates objects, or with `null` shows everything again. */
+type IsolationActionEffect = {
+    isolation: ViewerIsolation | null;
+};
+type ObjectActionEffect = IsolationActionEffect | ObjectBindingsActionEffect | SceneConfigActionEffect | VisibilityActionEffect | CameraActionEffect | AnimationActionEffect;
 
 type ObjectBindingAction = {
     id: "change-color" | "apply-texture" | "toggle-visibility" | string;
@@ -549,6 +780,33 @@ type ObjectBindingCameraState = {
     fov?: number;
     zoom?: number;
 };
+/**
+ * An image or a line of text printed onto the object's surface: a logo, a
+ * label, a personalisation.
+ */
+type ObjectBindingDecal = {
+    id: string;
+    /** The image to show: a URL or public path. */
+    image?: string;
+    /** Text to show, when there's no image. */
+    text?: string;
+    /** Text colour. Default `"#ffffff"`. */
+    color?: string;
+    /** CSS font family for the text. Default `"sans-serif"`. */
+    fontFamily?: string;
+    /** Default `"bold"`. */
+    fontWeight?: "normal" | "bold";
+    /** Where it sits on the object, in the object's own (local) space. */
+    position: [number, number, number];
+    /** The way the surface faces there, in the object's own space. */
+    normal: [number, number, number];
+    /** Width, in model units; the height follows the image or text's shape. */
+    size: number;
+    /** A turn around the surface normal, in radians. Default `0`. */
+    rotation?: number;
+    /** 0–1. Default `1`. */
+    opacity?: number;
+};
 type ObjectBindingStyle = {
     material?: ObjectBindingMaterial;
 };
@@ -566,6 +824,8 @@ type ObjectBinding = {
     hoverable?: boolean;
     transform?: ObjectBindingTransform;
     style?: ObjectBindingStyle;
+    /** Images and text printed on the object's surface. */
+    decals?: ObjectBindingDecal[];
     actions?: ObjectBindingAction[];
     metrics?: Record<string, number>;
     metadata?: Record<string, unknown>;
@@ -578,6 +838,12 @@ type ObjectActionEvent = {
     screenX?: number;
     screenY?: number;
 };
+/** A point on an object's surface, in the object's own (local) space. */
+type ObjectSurfacePoint = {
+    position: [number, number, number];
+    /** The way the surface faces at that point. */
+    normal: [number, number, number];
+};
 /** A double-click, right-click, or long-press on a model object. */
 type ObjectPointerEvent = {
     binding: ObjectBinding;
@@ -586,6 +852,11 @@ type ObjectPointerEvent = {
     clientY: number;
     /** `"mouse"`, `"pen"`, or `"touch"`. */
     pointerType: string;
+    /**
+     * Where on the object the pointer was, e.g. to place a decal there. Not
+     * reported for streamed (3D Tiles) models.
+     */
+    surface?: ObjectSurfacePoint;
 };
 
 /** One bindable object in a model, as reported by `onObjectCatalog`. */
@@ -601,4 +872,4 @@ type ViewerObjectInfo = {
     maximum: [number, number, number];
 };
 
-export { type SceneWireframeConfig as $, type AnimationAction as A, type BindingEdit as B, type CameraAction as C, DEFAULT_SCENE_CONFIG as D, type EnvironmentPreset as E, type SceneCameraConfig as F, type GlitchModeName as G, type SceneCinematicConfig as H, type SceneCinematicWaypoint as I, type SceneConfig as J, type KernelSizeName as K, type SceneConfigActionEffect as L, MATERIAL_BLENDING_MODES as M, type SceneConfigPatch as N, type ObjectActionEffect as O, type SceneEnvironmentConfig as P, type SceneGroundShadowConfig as Q, type RampTypeName as R, type SceneAnimationClipConfig as S, type SceneLight as T, type SceneLightAttachment as U, type SceneLightType as V, type SceneLightingConfig as W, type SceneModelConfig as X, type SceneModelRenderer as Y, type ScenePostProcessingConfig as Z, type SceneShadowConfig as _, type AnimationActionEffect as a, type ViewerCameraConfig as a0, type ViewerCameraState as a1, type ViewerObjectInfo as a2, type VisibilityActionEffect as a3, material as a4, patchBindings as a5, patchSceneConfig as a6, selectBindingKeys as a7, selectBindings as a8, type AnimationLoopMode as b, type CameraActionEffect as c, type DeepPartial as d, MATERIAL_SIDES as e, type ObjectActionEvent as f, type ObjectBinding as g, type ObjectBindingAction as h, type ObjectBindingCameraState as i, type ObjectBindingMaterial as j, type ObjectBindingMaterialBlendingMode as k, type ObjectBindingMaterialSide as l, type ObjectBindingPatch as m, type ObjectBindingSelector as n, type ObjectBindingStatus as o, type ObjectBindingStyle as p, type ObjectBindingTarget as q, type ObjectBindingTextureChannel as r, type ObjectBindingTextureSlot as s, type ObjectBindingTransform as t, type ObjectBindingType as u, type ObjectBindingsActionEffect as v, type ObjectPointerEvent as w, type SceneAnimationConfig as x, type SceneAnnotationMarker as y, type SceneBackgroundConfig as z };
+export { type SceneConfigPatch as $, type AnimationAction as A, type BindingEdit as B, type CameraAction as C, DEFAULT_SCENE_CONFIG as D, type EnvironmentPreset as E, type ObjectBindingTextureChannel as F, type GlitchModeName as G, type ObjectBindingTextureSlot as H, type IsolatedObjectBindings as I, type ObjectBindingTransform as J, type KernelSizeName as K, type ObjectBindingType as L, MATERIAL_BLENDING_MODES as M, type ObjectBindingsActionEffect as N, type ObjectActionEffect as O, type ObjectPointerEvent as P, type ObjectSurfacePoint as Q, type RampTypeName as R, type SceneAnimationClipConfig as S, type SceneAnimationConfig as T, type SceneAnnotationMarker as U, type SceneBackgroundConfig as V, type SceneCameraConfig as W, type SceneCinematicConfig as X, type SceneCinematicWaypoint as Y, type SceneConfig as Z, type SceneConfigActionEffect as _, type AnimationActionEffect as a, type SceneEnvironmentConfig as a0, type SceneGroundShadowConfig as a1, type SceneLight as a2, type SceneLightAttachment as a3, type SceneLightType as a4, type SceneLightingConfig as a5, type SceneModelConfig as a6, type SceneModelRenderer as a7, type ScenePostProcessingConfig as a8, type SceneSectionAxis as a9, type SceneSectionConfig as aa, type SceneShadowConfig as ab, type SceneStyleColorScale as ac, type SceneStyleCondition as ad, type SceneStylePulse as ae, type SceneStyleRule as af, type SceneWireframeConfig as ag, type StyledObjectBindings as ah, type StyledObjectPulse as ai, type ViewerAnimationsProps as aj, type ViewerCameraConfig as ak, type ViewerCameraState as al, type ViewerIsolation as am, type ViewerObjectInfo as an, type VisibilityActionEffect as ao, applyIsolation as ap, applyStyleRules as aq, colorScaleValue as ar, isolatedBindingKeys as as, material as at, patchBindings as au, patchSceneConfig as av, selectBindingKeys as aw, selectBindings as ax, useViewerAnimations as ay, type AnimationClipInfo as b, type AnimationClipState as c, type AnimationClipStatus as d, type AnimationControls as e, type AnimationLoopMode as f, type AnimationPlayOptions as g, type AnimationPlaybackState as h, type CameraActionEffect as i, DEFAULT_SECTION_CONFIG as j, type DeepPartial as k, type IsolationActionEffect as l, MATERIAL_SIDES as m, type ObjectActionEvent as n, type ObjectBinding as o, type ObjectBindingAction as p, type ObjectBindingCameraState as q, type ObjectBindingDecal as r, type ObjectBindingMaterial as s, type ObjectBindingMaterialBlendingMode as t, type ObjectBindingMaterialSide as u, type ObjectBindingPatch as v, type ObjectBindingSelector as w, type ObjectBindingStatus as x, type ObjectBindingStyle as y, type ObjectBindingTarget as z };

package/dist/simple-model-viewer.d.mts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { M as ModelFormat, a as ViewerModelInfo } from './modelInfo-CEmmvVCH.mjs';
-export { V as ViewerModelBounds } from './modelInfo-CEmmvVCH.mjs';
+import { M as ModelFormat, a as ViewerModelInfo } from './modelInfo-DnkmTGMd.mjs';
+export { V as ViewerModelBounds } from './modelInfo-DnkmTGMd.mjs';
 import { PresetsType } from '@react-three/drei/helpers/environment-assets';
 
 type SimpleModelViewerProps = {

package/dist/simple-model-viewer.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { M as ModelFormat, a as ViewerModelInfo } from './modelInfo-CEmmvVCH.js';
-export { V as ViewerModelBounds } from './modelInfo-CEmmvVCH.js';
+import { M as ModelFormat, a as ViewerModelInfo } from './modelInfo-DnkmTGMd.js';
+export { V as ViewerModelBounds } from './modelInfo-DnkmTGMd.js';
 import { PresetsType } from '@react-three/drei/helpers/environment-assets';
 
 type SimpleModelViewerProps = {