@ericchen1990/pano-view 2.0.0 → 2.2.0

package/dist/index.d.mts

@@ -790,14 +790,25 @@ declare function TouchControls({ enabled, rotateSpeed, invert, pinchZoom, }: Tou
 
 type SphereProps = {
     src: string;
+    /**
+     * Low-resolution 2:1 equirectangular image shown while `src` loads.
+     * Relative paths resolve against the directory of `src`. Root-absolute and
+     * `http(s)` / `blob:` / `data:` URLs are used as-is. For krpano sphere
+     * scenes, copy `<preview url>`.
+     */
+    previewUrl: string;
     /** Horizontal image offset in degrees. */
     yawOffset?: number;
+    /** Called once the first paintable texture (preview or `src`) is ready. */
+    onReady?: () => void;
     onLoad?: (texture: Texture) => void;
     onError?: (error: unknown) => void;
+    /** Called when `previewUrl` cannot be loaded; `src` still continues. */
+    onPreviewError?: (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;
+declare function Sphere({ src, previewUrl, yawOffset, onReady, onLoad, onError, onPreviewError, visible, }: SphereProps): react.JSX.Element | null;
 
 type VideoPlaybackState = "playing" | "paused" | "ended" | "blocked";
 type VideoHotspotErrorEvent = {
@@ -1001,18 +1012,30 @@ type TileLoadError = {
 };
 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;
-    /** Defaults to `${baseUrl}/previews/cube-vertical.webp`. */
-    previewUrl?: string | null;
+    /**
+     * 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`.
+     * `l/f/r/b/u/d`, matching krpano `preview.striporder` `LFRBUD`.
      */
     previewFaceOrder?: readonly CubeFaceCode[];
     /**
-     * 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`.
+     * 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 path relative to `baseUrl`; takes precedence over `urlTemplate`. */
@@ -1040,6 +1063,7 @@ type SphereScene = {
     id: string;
     type: "sphere";
     src: string;
+    previewUrl: string;
     yawOffset?: number;
 };
 type TileScene = Omit<TileProps, "loadMode" | "visible" | "onReady" | "onPreviewError" | "onLoadProgress" | "onTileError" | "onLevelChange"> & {

package/dist/index.d.ts

@@ -790,14 +790,25 @@ declare function TouchControls({ enabled, rotateSpeed, invert, pinchZoom, }: Tou
 
 type SphereProps = {
     src: string;
+    /**
+     * Low-resolution 2:1 equirectangular image shown while `src` loads.
+     * Relative paths resolve against the directory of `src`. Root-absolute and
+     * `http(s)` / `blob:` / `data:` URLs are used as-is. For krpano sphere
+     * scenes, copy `<preview url>`.
+     */
+    previewUrl: string;
     /** Horizontal image offset in degrees. */
     yawOffset?: number;
+    /** Called once the first paintable texture (preview or `src`) is ready. */
+    onReady?: () => void;
     onLoad?: (texture: Texture) => void;
     onError?: (error: unknown) => void;
+    /** Called when `previewUrl` cannot be loaded; `src` still continues. */
+    onPreviewError?: (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;
+declare function Sphere({ src, previewUrl, yawOffset, onReady, onLoad, onError, onPreviewError, visible, }: SphereProps): react.JSX.Element | null;
 
 type VideoPlaybackState = "playing" | "paused" | "ended" | "blocked";
 type VideoHotspotErrorEvent = {
@@ -1001,18 +1012,30 @@ type TileLoadError = {
 };
 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;
-    /** Defaults to `${baseUrl}/previews/cube-vertical.webp`. */
-    previewUrl?: string | null;
+    /**
+     * 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`.
+     * `l/f/r/b/u/d`, matching krpano `preview.striporder` `LFRBUD`.
      */
     previewFaceOrder?: readonly CubeFaceCode[];
     /**
-     * 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`.
+     * 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 path relative to `baseUrl`; takes precedence over `urlTemplate`. */
@@ -1040,6 +1063,7 @@ type SphereScene = {
     id: string;
     type: "sphere";
     src: string;
+    previewUrl: string;
     yawOffset?: number;
 };
 type TileScene = Omit<TileProps, "loadMode" | "visible" | "onReady" | "onPreviewError" | "onLoadProgress" | "onTileError" | "onLevelChange"> & {