@ericchen1990/pano-view 3.4.2 → 3.6.0

package/dist/data.d.mts

@@ -0,0 +1,581 @@
+import { CSSProperties } from 'react';
+
+type PanoDataErrorCode = "INVALID_OPTIONS" | "FETCH_FAILED" | "HTTP_ERROR" | "INVALID_JSON" | "INVALID_CONFIG" | "UNSUPPORTED_SCHEMA_VERSION" | "UNSUPPORTED_PROJECTION" | "INVALID_PROJECT" | "INVALID_REFERENCE" | "ABORTED";
+declare class PanoDataError extends Error {
+    readonly code: PanoDataErrorCode;
+    readonly status?: number;
+    readonly sceneId?: string;
+    readonly field?: string;
+    readonly cause?: unknown;
+    constructor(code: PanoDataErrorCode, message: string, details?: {
+        status?: number;
+        sceneId?: string;
+        field?: string;
+        cause?: unknown;
+    });
+}
+
+/** The portable rendering contract shared by the converter and browser viewer. */
+type ViewerCubeFace = "f" | "r" | "b" | "l" | "u" | "d";
+type CubemapViewerConfig = {
+    type: "tile";
+    multires: {
+        tileSize: number;
+        levels: number[];
+    };
+    urlTemplate: string;
+    previewUrl: string;
+    previewFaceOrder: ViewerCubeFace[];
+};
+type SphereViewerConfig = {
+    type: "sphereTile";
+    multires: {
+        tileSize: number;
+        levels: {
+            width: number;
+            height: number;
+        }[];
+    };
+    urlTemplate: string;
+    previewUrl: string;
+    indexBase: 0 | 1;
+};
+type ViewerConfig = CubemapViewerConfig | SphereViewerConfig;
+type ViewerDocument = ViewerConfig & {
+    schemaVersion: 1;
+};
+
+/** Camera-center limits in degrees. A yaw min greater than max crosses ±180°. */
+type PanoViewLimits = {
+    yaw?: {
+        min: number;
+        max: number;
+    };
+    pitch?: {
+        min: number;
+        max: number;
+    };
+    fov?: {
+        min: number;
+        max: number;
+    };
+};
+
+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;
+    /**
+     * Tile size followed by ascending cube-face sizes (`TILESIZE,LEVELSIZE1,...`).
+     * For krpano output, copy `image.cube.multires` from the XML.
+     */
+    multires: string | TileMultiresConfig;
+    /**
+     * Preview atlas path. Relative paths resolve against `baseUrl`; root-absolute
+     * and `http(s)` / `blob:` / `data:` URLs are used as-is. For krpano output,
+     * copy `<preview url>` (often `preview.jpg` at the scene root). This package's
+     * common cube atlas path is `previews/cube-vertical.webp`.
+     */
+    previewUrl: string;
+    /**
+     * Face order in the vertical preview atlas, from top to bottom. Defaults to
+     * `l/f/r/b/u/d`, matching krpano `preview.striporder` `LFRBUD`.
+     */
+    previewFaceOrder?: readonly CubeFaceCode[];
+    /**
+     * Path relative to `baseUrl`. Defaults to
+     * `tiles/%s/l%l/%v/l%l_%s_%h_%v.webp`. For krpano output, copy `<cube url>`
+     * from the XML; krpano templates often use `%v_%h` instead of this default
+     * `%h_%v`, so omitting `urlTemplate` requests the wrong files. 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 relative path or absolute URL; 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 SphereTileLevel = {
+    width: number;
+    height: number;
+};
+type SphereTileMultiresConfig = {
+    tileSize: number;
+    /** Ascending image dimensions. The first item maps to level 0. */
+    levels: SphereTileLevel[];
+};
+type SphereTileAddress = {
+    /** Zero-based logical level, column and row; URL indices add indexBase. */
+    level: number;
+    col: number;
+    row: number;
+    imageWidth: number;
+    imageHeight: number;
+    tileSize: number;
+    /** Actual tile dimensions, including partial edge tiles. */
+    width: number;
+    height: number;
+};
+type SphereTileLoadError = {
+    address: SphereTileAddress;
+    url: string;
+    error: unknown;
+};
+type SphereTileProps = {
+    baseUrl: string;
+    /** `512,500x250,1000x500,2000x1000` or explicit ascending dimensions. */
+    multires: string | SphereTileMultiresConfig;
+    /** A 2:1 equirectangular preview, resolved relative to baseUrl. */
+    previewUrl: string;
+    /** Defaults to `tiles/%l/%h_%v.webp`. No tile overlap. */
+    urlTemplate?: string;
+    /** URL indices start at 1 for krpano (default), or 0 for raw Sharp Deep Zoom. */
+    indexBase?: 0 | 1;
+    /** Takes precedence over urlTemplate and indexBase. Receives zero-based addresses. */
+    resolveTileUrl?: (address: SphereTileAddress) => string;
+    /** Horizontal source rotation in degrees. Defaults to 0. */
+    yawOffset?: number;
+    /** Tile cache budget in MiB. Defaults to 128. Preview memory is separate. */
+    maxTextureMemoryMb?: number;
+    /** Defaults to 4. */
+    maxConcurrentLoads?: number;
+    /** Retries after the initial attempt. Defaults to 1. */
+    retryCount?: number;
+    loadMode?: "full" | "preview" | "base";
+    visible?: boolean;
+    /** First paintable preview or tile is ready, even if the preview failed. */
+    onReady?: () => void;
+    onPreviewError?: (error: unknown) => void;
+    onLoadProgress?: (progress: TileLoadProgress) => void;
+    onTileError?: (event: SphereTileLoadError) => void;
+    /** Zero-based selected level. */
+    onLevelChange?: (level: number) => void;
+};
+
+type SceneViewOptions = {
+    viewLimits?: PanoViewLimits;
+};
+type TileScene = Omit<TileProps, "loadMode" | "visible" | "onReady" | "onPreviewError" | "onLoadProgress" | "onTileError" | "onLevelChange"> & SceneViewOptions & {
+    id: string;
+    type: "tile";
+};
+type SphereTileScene = Omit<SphereTileProps, "loadMode" | "visible" | "onReady" | "onPreviewError" | "onLoadProgress" | "onTileError" | "onLevelChange"> & SceneViewOptions & {
+    id: string;
+    type: "sphereTile";
+};
+
+type AssetUrlContext = {
+    defaultUrl: string;
+    kind: "tile" | "preview" | "hotspot";
+    sceneId: string;
+    hotspotId?: string;
+};
+type AssetUrlResolver = (path: string, context: AssetUrlContext) => string;
+type JsonRequestOptions = {
+    requestInit?: Pick<RequestInit, "headers" | "credentials" | "signal">;
+};
+type SceneFromViewerConfigOptions = {
+    id: string;
+    baseUrl: string;
+    resolveAssetUrl?: AssetUrlResolver;
+};
+type LoadSceneFromJsonOptions = Omit<SceneFromViewerConfigOptions, "baseUrl"> & JsonRequestOptions & {
+    baseUrl?: string;
+};
+declare function sceneFromViewerConfig(value: unknown, options: SceneFromViewerConfigOptions): TileScene | SphereTileScene;
+declare function loadSceneFromJson(url: string, options: LoadSceneFromJsonOptions): Promise<TileScene | SphereTileScene>;
+
+type ProjectPopupBlock = {
+    id: string;
+} & ({
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    src: string;
+    alt?: string;
+} | {
+    type: "video";
+    src: string;
+    poster?: string;
+} | {
+    type: "audio";
+    src: string;
+});
+type ProjectPopupDefinition = {
+    id: string;
+    title: string;
+    blocks: ProjectPopupBlock[];
+};
+type PopupAssetUrlContext = {
+    defaultUrl: string;
+    popupId: string;
+    blockId: string;
+    field: "src" | "poster";
+};
+type PopupAssetUrlResolver = (path: string, context: PopupAssetUrlContext) => string;
+declare function resolveProjectPopupAssets(popup: ProjectPopupDefinition, baseUrl: string, resolver?: PopupAssetUrlResolver): ProjectPopupDefinition;
+
+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";
+/** When a hotspot tooltip is shown. Defaults to `"always"`. */
+type HotspotTooltipTrigger = "always" | "hover" | "click";
+/**
+ * Pointer hit-testing for a hotspot. `"none"` ignores mouse, touch, and pen
+ * so events pass through to the panorama. Defaults to `"auto"`.
+ */
+type HotspotPointerEvents = "auto" | "none";
+/** Where the tooltip sits relative to the hotspot. Defaults to `"top"`. */
+type HotspotTooltipPlacement = "top" | "bottom" | "left" | "right";
+/** Plain-text and/or image content for a hotspot tooltip. */
+type HotspotTooltipContent = {
+    text?: string;
+    image?: string;
+    imageAlt?: string;
+};
+/** Visual styling for a hotspot tooltip bubble. */
+type HotspotTooltipAppearance = {
+    background?: string;
+    color?: string;
+    border?: string;
+    borderRadius?: number | string;
+    shadow?: string;
+    padding?: number | string;
+    fontSize?: number | string;
+    fontFamily?: CSSProperties["fontFamily"];
+    /** Unitless line-height, or a CSS length. */
+    lineHeight?: CSSProperties["lineHeight"];
+    /** Numbers are CSS pixels. */
+    letterSpacing?: CSSProperties["letterSpacing"];
+};
+
+type PanoViewerState = {
+    /** 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 GraphicPaint = {
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+};
+type CircleGraphic = GraphicPaint & {
+    kind: "circle";
+};
+type TriangleGraphic = GraphicPaint & {
+    kind: "triangle";
+};
+type DiamondGraphic = GraphicPaint & {
+    kind: "diamond";
+};
+type StarGraphic = GraphicPaint & {
+    kind: "star";
+};
+type ArrowGraphic = GraphicPaint & {
+    kind: "arrow";
+};
+type RectangleGraphic = GraphicPaint & {
+    kind: "rectangle";
+    /** Relative radius from 0 (square corners) to 0.5 (maximum rounded corners). */
+    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 | TriangleGraphic | DiamondGraphic | StarGraphic | ArrowGraphic | RectangleGraphic | RingGraphic | SvgGraphic | SvgPathGraphic;
+
+type IframePointerPolicy = "hotspot" | "content";
+
+type TextHotspotAlign = "left" | "center" | "right";
+type TextHotspotVerticalAlign = "top" | "middle" | "bottom";
+type TextHotspotWhiteSpace = "normal" | "nowrap";
+type TextHotspotFontStyle = "normal" | "italic";
+/** Serializable typography and panel paint for a text hotspot. */
+type TextHotspotStyle = {
+    fontFamily?: string;
+    /** Canvas pixels. Defaults to 96. */
+    fontSize?: number;
+    /** CSS font-weight. Defaults to 600. */
+    fontWeight?: number | string;
+    /** CSS font-style. Defaults to `"normal"`. */
+    fontStyle?: TextHotspotFontStyle;
+    color?: string;
+    /** CSS color. An empty string skips the panel fill. */
+    background?: string;
+    backgroundOpacity?: number;
+    /** Fraction of the texture's shorter side. */
+    padding?: number;
+    align?: TextHotspotAlign;
+    verticalAlign?: TextHotspotVerticalAlign;
+    lineHeight?: number;
+    whiteSpace?: TextHotspotWhiteSpace;
+    /** Fraction of the texture's shorter side, from 0 to 0.5. */
+    borderRadius?: number;
+    stroke?: string;
+    strokeWidth?: number;
+};
+
+/** 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;
+    /** Pointer hit-testing. `"none"` ignores mouse, touch, and pen. */
+    pointerEvents?: HotspotPointerEvents;
+    /** Canvas cursor while this hotspot is hovered. */
+    cursor?: CSSProperties["cursor"];
+    renderOrder?: number;
+    tooltip?: string | HotspotTooltipContent;
+    tooltipTrigger?: HotspotTooltipTrigger;
+    tooltipPlacement?: HotspotTooltipPlacement;
+    tooltipOffset?: number;
+    tooltipAppearance?: HotspotTooltipAppearance;
+};
+/** Shared serializable fields for a hotspot anchored at one yaw/pitch point. */
+type PointHotspotDefinitionBase = HotspotDefinitionBase & {
+    position: HotspotPosition;
+    width?: number;
+    height?: number;
+    scale?: 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 AudioHotspotDefinition = PointHotspotDefinitionBase & {
+    type: "audio";
+    src: string | string[];
+    format?: string | string[];
+    playing?: boolean;
+    loop?: boolean;
+    muted?: boolean;
+    volume?: number;
+    pauseWhenHidden?: boolean;
+    range?: number;
+    icon?: string;
+    playingIcon?: string;
+    marker?: boolean;
+    crossOrigin?: "" | "anonymous" | "use-credentials";
+};
+type TextHotspotDefinition = PointHotspotDefinitionBase & TextHotspotStyle & {
+    type: "text";
+    text: string;
+};
+type IframeHotspotDefinition = PointHotspotDefinitionBase & {
+    type: "iframe";
+    src: string;
+    title?: string;
+    sandbox?: string;
+    allow?: string;
+    referrerPolicy?: string;
+    loading?: "eager" | "lazy";
+    pointerPolicy?: IframePointerPolicy;
+    background?: string;
+};
+type PolygonHotspotDefinition = HotspotDefinitionBase & {
+    type: "polygon";
+    vertices: HotspotPosition[];
+    fill?: string;
+    fillOpacity?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    strokeOpacity?: number;
+    strokeDashSize?: number;
+    strokeGapSize?: number;
+};
+/** An open path. This extends the original point and polygon hotspot categories. */
+type PolylineHotspotDefinition = HotspotDefinitionBase & {
+    type: "polyline";
+    vertices: HotspotPosition[];
+    stroke?: string;
+    strokeWidth?: number;
+    strokeOpacity?: number;
+    strokeDashSize?: number;
+    strokeGapSize?: number;
+};
+type PointHotspotDefinition = ImageHotspotDefinition | GraphicHotspotDefinition | SequenceHotspotDefinition | VideoHotspotDefinition | AudioHotspotDefinition | TextHotspotDefinition | IframeHotspotDefinition;
+/** A serializable, discriminated hotspot collection item. */
+type HotspotDefinition = PointHotspotDefinition | PolygonHotspotDefinition | PolylineHotspotDefinition;
+
+type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+declare const projectHotspotTriggers: readonly ["click", "pointerenter", "pointerleave"];
+type ProjectHotspotTrigger = typeof projectHotspotTriggers[number];
+type ProjectCustomHotspotAction = {
+    type: "custom";
+    actionId: string;
+    params?: JsonObject;
+};
+declare function hotspotAction(hotspot: ProjectHotspotDefinition, trigger: ProjectHotspotTrigger): ProjectHotspotAction | undefined;
+declare function setHotspotAction(hotspot: ProjectHotspotDefinition, trigger: ProjectHotspotTrigger, action?: ProjectHotspotAction): ProjectHotspotDefinition;
+type ProjectHotspotAction = ProjectCustomHotspotAction | {
+    type: "scene";
+    sceneId: string;
+} | {
+    type: "view";
+    view: PanoViewerState;
+    duration?: number;
+} | {
+    type: "popup";
+    popupId: string;
+};
+type ProjectHotspotDefinition = HotspotDefinition & {
+    /** Legacy click fallback. events.click takes precedence. */
+    action?: ProjectHotspotAction;
+    events?: Partial<Record<ProjectHotspotTrigger, ProjectHotspotAction>>;
+};
+declare function resolveHotspotAssets(hotspot: ProjectHotspotDefinition, baseUrl: string, sceneId: string, resolver?: AssetUrlResolver): ProjectHotspotDefinition;
+
+type PanoProjectSceneDefinition = {
+    id: string;
+    title?: string;
+    source: ({
+        viewerUrl: string;
+        viewerConfig?: never;
+    } | {
+        viewerConfig: ViewerConfig;
+        viewerUrl?: never;
+    }) & {
+        baseUrl?: string;
+    };
+    initialView?: Partial<PanoViewerState>;
+    viewLimits?: PanoViewLimits;
+    hotspots?: ProjectHotspotDefinition[];
+};
+type PanoProjectDefinition = {
+    schemaVersion: 1;
+    title?: string;
+    initialSceneId?: string;
+    scenes: PanoProjectSceneDefinition[];
+    popups?: ProjectPopupDefinition[];
+};
+type LoadedProjectScene = {
+    scene: TileScene | SphereTileScene;
+    title?: string;
+    initialView?: PanoViewerState;
+    hotspots: ProjectHotspotDefinition[];
+};
+type LoadedPanoProject = {
+    title?: string;
+    initialSceneId: string;
+    scenes: LoadedProjectScene[];
+    popups?: ProjectPopupDefinition[];
+};
+type LoadPanoProjectOptions = JsonRequestOptions & {
+    /** Directory used for project-relative references. Required for object input. */
+    baseUrl?: string;
+    resolveAssetUrl?: AssetUrlResolver;
+    resolvePopupAssetUrl?: PopupAssetUrlResolver;
+};
+/** Drafts permit empty scenes and unfinished popup titles/media; loading and export always validate strictly. */
+declare function parsePanoProject(value: unknown, options?: {
+    draft?: boolean;
+}): PanoProjectDefinition;
+declare function loadPanoProject(source: string | PanoProjectDefinition, options?: LoadPanoProjectOptions): Promise<LoadedPanoProject>;
+
+export { type AssetUrlContext, type AssetUrlResolver, type CubemapViewerConfig, type JsonObject, type JsonRequestOptions, type JsonValue, type LoadPanoProjectOptions, type LoadSceneFromJsonOptions, type LoadedPanoProject, type LoadedProjectScene, PanoDataError, type PanoDataErrorCode, type PanoProjectDefinition, type PanoProjectSceneDefinition, type PanoViewLimits, type PopupAssetUrlContext, type PopupAssetUrlResolver, type ProjectCustomHotspotAction, type ProjectHotspotAction, type ProjectHotspotDefinition, type ProjectHotspotTrigger, type ProjectPopupBlock, type ProjectPopupDefinition, type SceneFromViewerConfigOptions, type SphereViewerConfig, type ViewerConfig, type ViewerDocument, hotspotAction, loadPanoProject, loadSceneFromJson, parsePanoProject, projectHotspotTriggers, resolveHotspotAssets as resolveProjectHotspotAssets, resolveProjectPopupAssets, sceneFromViewerConfig, setHotspotAction };