@ericchen1990/pano-view 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,519 @@
+import * as react from 'react';
+import { ReactNode, ComponentPropsWithoutRef } from 'react';
+import { Texture, ColorRepresentation, Vector3 } from 'three';
+
+declare const MAX_HOTSPOT_PITCH = 89.9;
+type HotspotPosition = {
+    /** Horizontal panorama angle in degrees. Positive values look right. */
+    yaw: number;
+    /** Vertical panorama angle in degrees. Positive values look up. */
+    pitch: number;
+};
+/**
+ * A safe point-hotspot rendering mode.
+ *
+ * `surface` attaches the visual to the panorama shell. `billboard` floats it
+ * in front of the shell and keeps it facing the camera.
+ */
+type HotspotMode = "surface" | "billboard";
+/** Whether a hotspot grows with panorama zoom or preserves its screen size. */
+type HotspotScaleMode = "fov" | "fixed";
+type HotspotInputSource = "pointer" | "keyboard";
+type HotspotInteractionEvent = {
+    id: string;
+    position: HotspotPosition;
+    source: HotspotInputSource;
+    nativeEvent: MouseEvent | PointerEvent | KeyboardEvent;
+};
+type HotspotDragEvent = HotspotInteractionEvent & {
+    source: "pointer";
+    startPosition: HotspotPosition;
+};
+type HotspotCommonProps = {
+    id: string;
+    position: HotspotPosition;
+    /** Angular width in degrees. Defaults to 12. */
+    width?: number;
+    /** Angular height in degrees. Defaults to 8. */
+    height?: number;
+    /** Defaults to "billboard". */
+    mode?: HotspotMode;
+    /**
+     * World-space distance for `mode="billboard"`. Defaults to 10 and is capped
+     * when needed so the full hotspot remains inside the panorama shell.
+     */
+    distance?: number;
+    /** FOV grows/shrinks with zoom; fixed preserves the reference screen size. */
+    scaleMode?: HotspotScaleMode;
+    /** Reference FOV in degrees used when scaleMode is "fixed". Defaults to 75. */
+    referenceFov?: number;
+    /** Clockwise rotation around the hotspot normal in degrees. */
+    rotation?: number;
+    opacity?: number;
+    renderOrder?: number;
+    visible?: boolean;
+    /** Whether the hotspot accepts pointer and keyboard interaction. Defaults to true. */
+    interactive?: boolean;
+    draggable?: boolean;
+    /** Required for keyboard-accessible clickable hotspots. */
+    ariaLabel?: string;
+    onClick?: (event: HotspotInteractionEvent) => void;
+    onHoverChange?: (hovered: boolean, event: HotspotInteractionEvent) => void;
+    onDragStart?: (event: HotspotDragEvent) => void;
+    onPositionChange?: (event: HotspotDragEvent) => void;
+    onDragEnd?: (event: HotspotDragEvent) => void;
+};
+type PanoramaPointerEvent = {
+    position: HotspotPosition;
+    nativeEvent: MouseEvent | PointerEvent;
+    pointerId?: number;
+    button: number;
+    buttons: number;
+    clientX: number;
+    clientY: number;
+};
+
+type PanoViewState = {
+    /** Horizontal look angle in degrees. Positive values look right. */
+    yaw: number;
+    /** Vertical look angle in degrees. Positive values look up. */
+    pitch: number;
+    /** Vertical perspective field of view in degrees. */
+    fov: number;
+};
+type SetPanoViewOptions = {
+    /** Apply the new view immediately instead of preserving current inertia. */
+    immediate?: boolean;
+};
+type PanoViewHandle = {
+    getView: () => PanoViewState;
+    setView: (view: Partial<PanoViewState>, options?: SetPanoViewOptions) => void;
+    reset: () => void;
+    /** @deprecated Control an AutoRotate component's enabled prop instead. */
+    startAutoRotate: () => void;
+    /** @deprecated Control an AutoRotate component's enabled prop instead. */
+    stopAutoRotate: () => void;
+    toggleFullscreen: () => Promise<void>;
+};
+type PanoramaControlsOptions = {
+    /** Enables drag and zoom inertia. Defaults to true. */
+    inertia?: boolean;
+    /** @deprecated Render <AutoRotate enabled /> inside PanoView instead. */
+    autoRotate?: boolean;
+    /** @deprecated Use AutoRotate's speed prop instead. */
+    autoRotateSpeed?: number;
+    /** Pointer drag multiplier. Defaults to 0.35. */
+    rotateSpeed?: number;
+    /** Wheel zoom multiplier. Defaults to 0.08. */
+    zoomSpeed?: number;
+    /**
+     * Rotation target-following speed in seconds^-1. Defaults to 14; use 0 for
+     * immediate response. Must be a non-negative finite number.
+     */
+    rotateDamping?: number;
+    /**
+     * FOV target-following speed in seconds^-1. Defaults to 16; use 0 for
+     * immediate response. Must be a non-negative finite number.
+     */
+    zoomDamping?: number;
+    /** Enables focusable keyboard controls. Defaults to true. */
+    keyboard?: boolean;
+};
+
+type PanoViewProps = Omit<ComponentPropsWithoutRef<"div">, "children" | "onChange"> & {
+    children?: ReactNode;
+    initialView?: Partial<PanoViewState>;
+    minFov?: number;
+    maxFov?: number;
+    controls?: boolean | PanoramaControlsOptions;
+    onViewChange?: (view: PanoViewState) => void;
+    onPanoramaClick?: (event: PanoramaPointerEvent) => void;
+    onPanoramaDoubleClick?: (event: PanoramaPointerEvent) => void;
+    onPanoramaPointerMove?: (event: PanoramaPointerEvent) => void;
+    /** Canvas pixel ratio. Defaults to a capped range of 1–2. */
+    dpr?: number | [number, number];
+};
+declare const PanoView: react.ForwardRefExoticComponent<Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "children" | "onChange"> & {
+    children?: ReactNode;
+    initialView?: Partial<PanoViewState>;
+    minFov?: number;
+    maxFov?: number;
+    controls?: boolean | PanoramaControlsOptions;
+    onViewChange?: (view: PanoViewState) => void;
+    onPanoramaClick?: (event: PanoramaPointerEvent) => void;
+    onPanoramaDoubleClick?: (event: PanoramaPointerEvent) => void;
+    onPanoramaPointerMove?: (event: PanoramaPointerEvent) => void;
+    /** Canvas pixel ratio. Defaults to a capped range of 1–2. */
+    dpr?: number | [number, number];
+} & react.RefAttributes<PanoViewHandle>>;
+
+/** Options for automatic horizontal panorama rotation. */
+type AutoRotateProps = {
+    /** Whether automatic rotation is active. Defaults to true. */
+    enabled?: boolean;
+    /** Rotation speed in degrees per second. Negative values rotate left. */
+    speed?: number;
+    /**
+     * Rate at which rotation reaches its target speed, in degrees per second
+     * squared. Use 0 to disable the speed ramp. Defaults to 18.
+     */
+    acceleration?: number;
+    /** Milliseconds to wait after enabling before rotation begins. */
+    startDelay?: number;
+};
+/**
+ * Adds automatic rotation to the nearest PanoView. Render one instance as a
+ * child of PanoView, alongside its panorama source.
+ */
+declare function AutoRotate({ enabled, speed, acceleration, startDelay, }: AutoRotateProps): null;
+
+type SphereProps = {
+    src: string;
+    /** Horizontal image offset in degrees. */
+    yawOffset?: number;
+    onLoad?: (texture: Texture) => void;
+    onError?: (error: unknown) => void;
+    /** Keeps the source mounted for preloading without drawing it. */
+    visible?: boolean;
+};
+declare function Sphere({ src, yawOffset, onLoad, onError, visible, }: SphereProps): react.JSX.Element | null;
+
+type CubeFaceCode = "f" | "r" | "b" | "l" | "u" | "d";
+type TileAddress = {
+    face: CubeFaceCode;
+    level: number;
+    row: number;
+    col: number;
+    faceSize: number;
+    tileSize: number;
+    width: number;
+    height: number;
+};
+type TileMultiresConfig = {
+    tileSize: number;
+    /** Ascending face sizes. The first value maps to l1. */
+    levels: number[];
+};
+type TileLoadProgress = {
+    requested: number;
+    loaded: number;
+    failed: number;
+    active: number;
+    queued: number;
+};
+type TileLoadError = {
+    address: TileAddress;
+    url: string;
+    error: unknown;
+};
+type TileProps = {
+    baseUrl: string;
+    multires: string | TileMultiresConfig;
+    /** Defaults to `${baseUrl}/previews/cube-vertical.webp`. */
+    previewUrl?: string | null;
+    /**
+     * Relative to `baseUrl`; supports krpano cube-tile `%s` and `%l` placeholders,
+     * horizontal `%h`/`%x`/`%u`/`%c`, vertical `%v`/`%y`/`%w`/`%r`, and index padding
+     * such as `%0h` or `%00v`.
+     */
+    urlTemplate?: string;
+    /** Returns a path relative to `baseUrl`; takes precedence over `urlTemplate`. */
+    resolveTileUrl?: (address: TileAddress) => string;
+    maxTextureMemoryMb?: number;
+    maxConcurrentLoads?: number;
+    retryCount?: number;
+    /**
+     * `preview` loads only the preview atlas; `base` also preloads the visible
+     * lowest-resolution tiles before full-resolution loading begins.
+     */
+    loadMode?: "full" | "preview" | "base";
+    /** Keeps the source mounted for preloading without drawing it. */
+    visible?: boolean;
+    /** Called when the preview atlas is ready for display. */
+    onReady?: () => void;
+    /** Called when the preview atlas cannot be loaded. */
+    onPreviewError?: (error: unknown) => void;
+    onLoadProgress?: (progress: TileLoadProgress) => void;
+    onTileError?: (event: TileLoadError) => void;
+    onLevelChange?: (level: number) => void;
+};
+
+type PanoramaTransitionPreset = "none" | "crossfade" | "zoom" | "blackout" | "whiteFlash" | "slideRightToLeft" | "slideTopToBottom" | "slideDiagonal" | "circleOpen" | "verticalOpen" | "horizontalOpen" | "ellipticZoomOpen";
+type PanoramaTransition = PanoramaTransitionPreset | {
+    preset: PanoramaTransitionPreset;
+    /** Overrides the KRpano-compatible default duration in seconds. */
+    duration?: number;
+};
+type SpherePanoramaScene = {
+    id: string;
+    type: "sphere";
+    src: string;
+    yawOffset?: number;
+};
+type TilePanoramaScene = Omit<TileProps, "loadMode" | "visible" | "onReady" | "onPreviewError" | "onLoadProgress" | "onTileError" | "onLevelChange"> & {
+    id: string;
+    type: "tile";
+};
+type PanoramaScene = SpherePanoramaScene | TilePanoramaScene;
+type PanoramaTransitionEndEvent = {
+    previousSceneId: string;
+    sceneId: string;
+    preset: PanoramaTransitionPreset;
+};
+type PanoramaTransitionErrorEvent = {
+    sceneId: string;
+    error: unknown;
+};
+type PanoramaScenesProps = {
+    scenes: readonly PanoramaScene[];
+    activeSceneId: string;
+    transition?: PanoramaTransition;
+    /** Rendered only after a scene has finished transitioning in. */
+    renderHotspots?: (scene: PanoramaScene) => ReactNode;
+    onTransitionEnd?: (event: PanoramaTransitionEndEvent) => void;
+    onTransitionError?: (event: PanoramaTransitionErrorEvent) => void;
+    /** Viewer-wide budget shared by every tile scene. Defaults to 128 MiB. */
+    maxTextureMemoryMb?: number;
+    /** Viewer-wide tile request limit. Defaults to 4. */
+    maxConcurrentTileLoads?: number;
+    /** Maximum physical-pixel area of the outgoing GPU snapshot. */
+    snapshotMaxPixels?: number;
+};
+declare function PanoramaScenes({ maxTextureMemoryMb, maxConcurrentTileLoads, ...props }: PanoramaScenesProps): react.JSX.Element;
+
+type ImageHotspotProps = HotspotCommonProps & {
+    src: string;
+    onLoad?: (texture: Texture) => void;
+    onError?: (error: unknown) => void;
+};
+declare function ImageHotspot({ src, width, height, opacity, onLoad, onError, ...anchorProps }: ImageHotspotProps): react.JSX.Element;
+
+type PolygonValidationCode = "too_few_vertices" | "self_intersection" | "contains_pole" | "outside_hemisphere";
+type PolygonValidationIssue = {
+    code: PolygonValidationCode;
+    message: string;
+};
+type PolygonVerticesChangeEvent = {
+    id: string;
+    vertices: HotspotPosition[];
+    startVertices: HotspotPosition[];
+    position: HotspotPosition;
+    startPosition: HotspotPosition;
+};
+type PolygonHotspotProps = Omit<HotspotCommonProps, "position" | "width" | "height" | "mode" | "distance" | "scaleMode" | "onDragStart" | "onPositionChange" | "onDragEnd"> & {
+    vertices: HotspotPosition[];
+    fill?: ColorRepresentation;
+    fillOpacity?: number;
+    stroke?: ColorRepresentation;
+    /** Screen-space border width in CSS pixels. Defaults to 2. */
+    strokeWidth?: number;
+    /** Opacity of the polygon boundary, from 0 to 1. Defaults to 1. */
+    strokeOpacity?: number;
+    onVerticesChange?: (event: PolygonVerticesChangeEvent) => void;
+    onDragStart?: (event: PolygonVerticesChangeEvent) => void;
+    onDragEnd?: (event: PolygonVerticesChangeEvent) => void;
+    onInvalid?: (issues: PolygonValidationIssue[]) => void;
+};
+type UnwrappedVertex = HotspotPosition & {
+    unwrappedYaw: number;
+};
+declare function unwrapPolygonVertices(vertices: HotspotPosition[]): UnwrappedVertex[];
+declare function validatePolygonVertices(vertices: HotspotPosition[]): PolygonValidationIssue[];
+declare function PolygonHotspot({ id, vertices, fill, fillOpacity, stroke, strokeWidth, strokeOpacity, interactive, renderOrder, draggable, onVerticesChange, onDragStart, onDragEnd, onInvalid, ...anchorProps }: PolygonHotspotProps): react.JSX.Element | null;
+
+type PolylineValidationIssue = {
+    code: "too_few_vertices";
+    message: string;
+};
+type PolylineVerticesChangeEvent = {
+    id: string;
+    vertices: HotspotPosition[];
+    startVertices: HotspotPosition[];
+    position: HotspotPosition;
+    startPosition: HotspotPosition;
+};
+type PolylineHotspotProps = Omit<HotspotCommonProps, "position" | "width" | "height" | "mode" | "distance" | "scaleMode" | "onDragStart" | "onPositionChange" | "onDragEnd"> & {
+    vertices: HotspotPosition[];
+    stroke?: ColorRepresentation;
+    /** Screen-space line width in CSS pixels. Defaults to 2. */
+    strokeWidth?: number;
+    strokeOpacity?: number;
+    onVerticesChange?: (event: PolylineVerticesChangeEvent) => void;
+    onDragStart?: (event: PolylineVerticesChangeEvent) => void;
+    onDragEnd?: (event: PolylineVerticesChangeEvent) => void;
+    onInvalid?: (issues: PolylineValidationIssue[]) => void;
+};
+declare function validatePolylineVertices(vertices: HotspotPosition[]): PolylineValidationIssue[];
+declare function PolylineHotspot({ id, vertices, stroke, strokeWidth, strokeOpacity, renderOrder, draggable, onVerticesChange, onDragStart, onDragEnd, onInvalid, ...anchorProps }: PolylineHotspotProps): react.JSX.Element | null;
+
+type GraphicPaint = {
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+};
+type CircleGraphic = GraphicPaint & {
+    kind: "circle";
+};
+type RectangleGraphic = GraphicPaint & {
+    kind: "rectangle";
+    cornerRadius?: number;
+};
+type RingGraphic = GraphicPaint & {
+    kind: "ring";
+    innerRadius?: number;
+};
+type SvgGraphic = {
+    kind: "svg";
+    src: string;
+};
+type SvgPathGraphic = GraphicPaint & {
+    kind: "path";
+    path: string;
+    viewBox: [x: number, y: number, width: number, height: number];
+};
+type GraphicDefinition = CircleGraphic | RectangleGraphic | RingGraphic | SvgGraphic | SvgPathGraphic;
+type GraphicHotspotProps = HotspotCommonProps & {
+    graphic: GraphicDefinition;
+    onLoad?: (texture: Texture) => void;
+    onError?: (error: unknown) => void;
+};
+declare function GraphicHotspot(props: GraphicHotspotProps): react.JSX.Element;
+
+type SequenceFrameDirection = "horizontal" | "vertical";
+type SequenceLoadProgress = {
+    id: string;
+    total: number;
+    loaded: number;
+    failed: number;
+};
+type SequenceFrameEvent = {
+    id: string;
+    index: number;
+    src: string;
+};
+type SequencePlaybackState = "playing" | "paused" | "ended";
+type SequenceHotspotErrorEvent = {
+    id: string;
+    src: string;
+    error: unknown;
+};
+type SequenceHotspotProps = HotspotCommonProps & {
+    /** A sprite sheet containing each frame in equally sized cells. */
+    src: string;
+    /** Number of cells in the sprite sheet, from left-to-right or top-to-bottom. */
+    frameCount: number;
+    frameDirection?: SequenceFrameDirection;
+    playing: boolean;
+    fps?: number;
+    loop?: boolean;
+    onFrameChange?: (event: SequenceFrameEvent) => void;
+    onLoadProgress?: (progress: SequenceLoadProgress) => void;
+    onPlaybackStateChange?: (state: SequencePlaybackState) => void;
+    onEnded?: () => void;
+    onError?: (event: SequenceHotspotErrorEvent) => void;
+};
+declare function SequenceHotspot({ id, src, frameCount: requestedFrameCount, frameDirection, playing, fps, loop, width, height, opacity, onFrameChange, onLoadProgress, onPlaybackStateChange, onEnded, onError, ...anchorProps }: SequenceHotspotProps): react.JSX.Element;
+
+type VideoPlaybackState = "playing" | "paused" | "ended" | "blocked";
+type VideoHotspotErrorEvent = {
+    id: string;
+    source: "poster" | "video";
+    error: unknown;
+};
+type VideoHotspotProps = HotspotCommonProps & {
+    src: string;
+    playing: boolean;
+    poster?: string;
+    loop?: boolean;
+    muted?: boolean;
+    volume?: number;
+    playsInline?: boolean;
+    preload?: "none" | "metadata" | "auto";
+    crossOrigin?: "" | "anonymous" | "use-credentials";
+    onPlaybackStateChange?: (state: VideoPlaybackState) => void;
+    onPlaybackError?: (error: unknown) => void;
+    onEnded?: () => void;
+    onError?: (event: VideoHotspotErrorEvent) => void;
+};
+declare function VideoHotspot({ id, src, playing, poster, loop, muted, volume, playsInline, preload, crossOrigin, width, height, opacity, onPlaybackStateChange, onPlaybackError, onEnded, onError, ...anchorProps }: VideoHotspotProps): react.JSX.Element;
+
+declare function Tile({ baseUrl, multires, previewUrl, urlTemplate, resolveTileUrl, maxTextureMemoryMb, maxConcurrentLoads, retryCount, loadMode, visible, onReady, onPreviewError, onLoadProgress, onTileError, onLevelChange, }: TileProps): react.JSX.Element;
+
+declare function normalizePanoYaw(yaw: number): number;
+declare function clampPanoPitch(pitch: number): number;
+declare function normalizePanoPosition(position: HotspotPosition): HotspotPosition;
+declare function panoPositionToVector3(position: HotspotPosition, radius?: number): Vector3;
+declare function vector3ToPanoPosition(vector: Pick<Vector3, "x" | "y" | "z">): HotspotPosition;
+
+/** Shared serializable fields for every saved hotspot definition. */
+type HotspotDefinitionBase = {
+    id: string;
+    /** Human-readable label; use it as the source for the rendered ariaLabel. */
+    label?: string;
+    visible?: boolean;
+    interactive?: boolean;
+    renderOrder?: number;
+};
+/** Shared serializable fields for a hotspot anchored at one yaw/pitch point. */
+type PointHotspotDefinitionBase = HotspotDefinitionBase & {
+    position: HotspotPosition;
+    width?: number;
+    height?: number;
+    mode?: HotspotMode;
+    distance?: number;
+    scaleMode?: HotspotScaleMode;
+    referenceFov?: number;
+    rotation?: number;
+    opacity?: number;
+};
+type ImageHotspotDefinition = PointHotspotDefinitionBase & {
+    type: "image";
+    src: string;
+};
+type GraphicHotspotDefinition = PointHotspotDefinitionBase & {
+    type: "graphic";
+    graphic: GraphicDefinition;
+};
+type SequenceHotspotDefinition = PointHotspotDefinitionBase & {
+    type: "sequence";
+    src: string;
+    frameCount: number;
+    frameDirection?: "horizontal" | "vertical";
+    playing?: boolean;
+    fps?: number;
+    loop?: boolean;
+};
+type VideoHotspotDefinition = PointHotspotDefinitionBase & {
+    type: "video";
+    src: string;
+    poster?: string;
+    playing?: boolean;
+    loop?: boolean;
+    muted?: boolean;
+    volume?: number;
+    playsInline?: boolean;
+    preload?: "none" | "metadata" | "auto";
+    crossOrigin?: "" | "anonymous" | "use-credentials";
+};
+type PolygonHotspotDefinition = HotspotDefinitionBase & {
+    type: "polygon";
+    vertices: HotspotPosition[];
+    fill?: string;
+    fillOpacity?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    strokeOpacity?: number;
+};
+/** An open path. This extends the original five hotspot categories. */
+type PolylineHotspotDefinition = HotspotDefinitionBase & {
+    type: "polyline";
+    vertices: HotspotPosition[];
+    stroke?: string;
+    strokeWidth?: number;
+    strokeOpacity?: number;
+};
+type PointHotspotDefinition = ImageHotspotDefinition | GraphicHotspotDefinition | SequenceHotspotDefinition | VideoHotspotDefinition;
+/** A serializable, discriminated hotspot collection item. */
+type HotspotDefinition = PointHotspotDefinition | PolygonHotspotDefinition | PolylineHotspotDefinition;
+
+export { AutoRotate, type AutoRotateProps, type CircleGraphic, type CubeFaceCode, type GraphicDefinition, GraphicHotspot, type GraphicHotspotDefinition, type GraphicHotspotProps, type HotspotCommonProps, type HotspotDefinition, type HotspotDefinitionBase, type HotspotDragEvent, type HotspotInputSource, type HotspotInteractionEvent, type HotspotMode, type HotspotPosition, type HotspotScaleMode, ImageHotspot, type ImageHotspotDefinition, type ImageHotspotProps, MAX_HOTSPOT_PITCH, PanoView, type PanoViewHandle, type PanoViewProps, type PanoViewState, type PanoramaControlsOptions, type PanoramaPointerEvent, type PanoramaScene, PanoramaScenes, type PanoramaScenesProps, type PanoramaTransition, type PanoramaTransitionEndEvent, type PanoramaTransitionErrorEvent, type PanoramaTransitionPreset, type PointHotspotDefinition, type PointHotspotDefinitionBase, PolygonHotspot, type PolygonHotspotDefinition, type PolygonHotspotProps, type PolygonValidationCode, type PolygonValidationIssue, type PolygonVerticesChangeEvent, PolylineHotspot, type PolylineHotspotDefinition, type PolylineHotspotProps, type PolylineValidationIssue, type PolylineVerticesChangeEvent, type RectangleGraphic, type RingGraphic, type SequenceFrameDirection, type SequenceFrameEvent, SequenceHotspot, type SequenceHotspotDefinition, type SequenceHotspotErrorEvent, type SequenceHotspotProps, type SequenceLoadProgress, type SequencePlaybackState, type SetPanoViewOptions, Sphere, type SpherePanoramaScene, type SphereProps, type SvgGraphic, type SvgPathGraphic, Tile, type TileAddress, type TileLoadError, type TileLoadProgress, type TileMultiresConfig, type TilePanoramaScene, type TileProps, VideoHotspot, type VideoHotspotDefinition, type VideoHotspotErrorEvent, type VideoHotspotProps, type VideoPlaybackState, clampPanoPitch, normalizePanoPosition, normalizePanoYaw, panoPositionToVector3, unwrapPolygonVertices, validatePolygonVertices, validatePolylineVertices, vector3ToPanoPosition };